Quickstart

In this quickstart you check your key, read your team’s customers, create a customer and read it back. You need a terminal with curl.

Caution

There’s no sandbox: everything here runs on your real team’s data. Step 3 creates a real customer, “TEST Northwind Apparel”, which you delete at the end. See Test your integration for safer ways to try writes.

1. Get your key and Team ID

API access comes with these plans:

Includes API access	Doesn’t
Pro, monthly or annual, and the Pro trial	Basic, and the Basic trial
The Special plan	Free
The older Essential and Enterprise plans	The older Starter plan

Creating a key in Profile also needs an active, paid subscription.

1. Sign in to YoPrint and open Profile.
2. Find the API Access card. If it says “You don’t have an API key yet.”, select Create API Key. Opening the page never creates a key.
3. Copy the key with the copy button next to it, which always copies the whole key. YoPrint shows a new key in full. After that the card shows it masked, and Reveal shows it again.
4. On the same card, copy the Team ID. That’s your team slug, the value that goes in every request path.

• No API Access card in Profile? Your team’s plan doesn’t include API access. A team owner can move the team to Pro or higher.
• The card says “API keys need an active subscription. If you’re on a trial and want to try the API, email support@yoprint.com.”? Your team is on a trial, and Profile creates keys only on a paid subscription. Email support to try the API during the trial. If you already have a key, it works on a Pro trial team too. See Test your integration.

Your key acts as you, with your role, on every team you belong to whose plan includes API access. Keep it secret. See Authentication.

2. Make your first request

The API Access card has a Make your first request section with this request, with your Team ID already in place of your-team. Copy it, replace YOUR_API_KEY with your key, and run it:

GET Check that your API key works for a team /v1/api/store/{team_slug}/is_authenticated

curl https://secure.yoprint.com/v1/api/store/your-team/is_authenticated \
  -H "Authorization: Bearer YOUR_API_KEY"

A working key and Team ID get back:

{
  "status": 200,
  "success": true,
  "data": { "is_authenticated": true }
}

That’s your first successful call. If you got something else:

You got	What it means	Fix
401 with "code": "unauthenticated"	The key is wrong, or it was regenerated.	Copy it again from Profile. Check that you replaced YOUR_API_KEY.
403 with "code": "api_access_not_in_plan"	The key works, but this team’s plan doesn’t include API access.	Use a team on Pro or higher, or upgrade this one.
404 with "code": "page_not_found"	The key works, but the Team ID is wrong, or you’re not a member of that team.	Copy the Team ID again.

The 403 looks like this:

{
  "status": 403,
  "success": false,
  "error": {
    "code": "api_access_not_in_plan",
    "message": "Your team's plan doesn't include API access. Upgrade to the Pro plan or higher in YoPrint, under Billing, to use the API, webhooks and Zapier."
  }
}

Put your key and Team ID in your shell so the commands below can use them:

export YOPRINT_API_KEY="YOUR_API_KEY"
export YOPRINT_TEAM="your-team"

From here on, each request also sends two headers:

• Accept: application/json, so that even a mistyped path answers JSON instead of an HTML page.
• X-Yoprint-Decimal-Format: exact-v1, so amounts come back exact. See Money and quantities.

Now read the first page of your team’s customers:

GET List customers /v1/api/store/{team_slug}/customer

curl "https://secure.yoprint.com/v1/api/store/$YOPRINT_TEAM/customer" \
  -H "Authorization: Bearer $YOPRINT_API_KEY" \
  -H "Accept: application/json" \
  -H "X-Yoprint-Decimal-Format: exact-v1"

The answer has the customers in data, and a pagination block that says how many there are and how many pages. Shortened:

{
  "status": 200,
  "success": true,
  "data": [
    { "id": "63KcENAAsKuipY", "name": "Alex Rivera", "tax_exempt": false }
  ],
  "pagination": { "count": 1, "total": 1, "perPage": 50, "currentPage": 1, "totalPages": 1, "links": [] }
}

Each customer’s id, such as 63KcENAAsKuipY, is how you name it in later requests. It isn’t the number people see in the web app. See IDs.

3. Make your first write

Create a customer with one contact:

POST Create a customer /v1/api/store/{team_slug}/customer

curl "https://secure.yoprint.com/v1/api/store/$YOPRINT_TEAM/customer" \
  -H "Authorization: Bearer $YOPRINT_API_KEY" \
  -H "Accept: application/json" \
  -H "X-Yoprint-Decimal-Format: exact-v1" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "TEST Northwind Apparel",
      "tax_exempt": false
    },
    "contact": [
      {
        "first_name": "Alex",
        "last_name": "Rivera",
        "email": "alex@example.com",
        "send_invoice": true,
        "is_primary": true
      }
    ]
  }'

• customer.name and customer.tax_exempt are required.
• contact is a list. Each contact needs first_name, send_invoice and is_primary. A phone number also needs its country, in phone_country.
• Use your own email address for the contact. Later guides can email this customer.

The answer is the new customer, with its contacts. Note its data.id:

{
  "status": 200,
  "success": true,
  "data": {
    "id": "VwYKuTP9vd8Dfo",
    "name": "TEST Northwind Apparel",
    "tax_exempt": false,
    "contacts": [
      { "id": "ZXhN3KtjHgQZFz", "first_name": "Alex", "last_name": "Rivera", "email": "alex@example.com" }
    ]
  }
}

Keep it in your shell for the next steps:

export CUSTOMER_ID="VwYKuTP9vd8Dfo"

If you get 422, the body’s error.fields names each field to fix. Nothing was created. Fix the request and send it again.

Caution

Don’t send a create twice. If the request times out, list or search your customers before you try again, or you may end up with two “TEST Northwind Apparel” customers. See Retries and duplicates.

The new customer is assigned to you, and YoPrint fires the customer.created webhook for any subscription that listens to it.

4. Read it back

GET Get a customer /v1/api/store/{team_slug}/customer/{hash_id}

curl "https://secure.yoprint.com/v1/api/store/$YOPRINT_TEAM/customer/$CUSTOMER_ID" \
  -H "Authorization: Bearer $YOPRINT_API_KEY" \
  -H "Accept: application/json" \
  -H "X-Yoprint-Decimal-Format: exact-v1"

You get the same customer, with its contacts and addresses. Open Customers in the web app and you’ll see it there too.

To try an order next, keep this customer and go to Quote to payment. It uses $CUSTOMER_ID.

5. Clean up

Delete the test customer:

DELETE Delete a customer /v1/api/store/{team_slug}/customer/{hash_id}

curl -X DELETE "https://secure.yoprint.com/v1/api/store/$YOPRINT_TEAM/customer/$CUSTOMER_ID" \
  -H "Authorization: Bearer $YOPRINT_API_KEY" \
  -H "Accept: application/json" \
  -H "X-Yoprint-Decimal-Format: exact-v1"

Deleting moves the customer to the trash, where it can be restored. A customer with an open quote or sales order can’t be deleted: YoPrint answers 422. Delete the order first.

What you learned

• Every request goes to https://secure.yoprint.com, with the version and your team slug at the start of the path.
• Every request carries Authorization: Bearer YOUR_API_KEY, and should carry Accept: application/json and X-Yoprint-Decimal-Format: exact-v1.
• Records are named by their id, from a previous answer.
• Answers have status, success and data. Lists add pagination.
• A create isn’t safe to repeat.

Next

• Quote to payment: create a sales order, add lines, invoice it and record a payment.
• Calling the API: the same calls in JavaScript, Python and PHP.
• Errors and Money and quantities: the two pages that prevent most bugs.