IDs

Every YoPrint record has an id. Use it whenever an operation needs to name a record: in the path, and in body fields that end in _id.

{
  "id": "V4keXwwxMQyXw7",
  "scoped_id": "SO1001",
  "customer_id": "VwYKuTP9vd8Dfo"
}

Three kinds of identifier

Field	What it is	Use it in requests?
id	The record’s hash id: a string of letters and digits, at least 14 long, with no prefix. Keep its upper and lower case.	Yes, everywhere.
unique_key	A second key on some records, starting with a type prefix such as ord_.	Only where a reference page says so.
scoped_id	The document number people see, such as the sales order number.	No. Search for it instead.

Note

The ids in these docs, such as V4keXwwxMQyXw7, are made up, but shaped like real ones. Treat every id as a string of letters and digits with no meaning of its own: never parse it, check its length or characters, change its case, or build one yourself.

Hash ids

• Read a record’s hash id from its id field, or from a related record’s *_id field, such as an order’s customer_id.
• Path parameters named {hash_id}, {id} or {hash_id2} take hash ids only.
• Body fields that point at another record, such as customer_id, payment_method_id or status_id, take hash ids.
• An id belongs to one team. It finds nothing on another team, even with the same key.

Unique keys

Sales orders, quotes and their lines, invoices and their lines, shipments and their lines, jobs and payment links also have a unique key, such as ord_ followed by a long string. Path parameters named {order_unique_key}, {unique_key} or {order_item_unique_key} accept either the hash id or the unique key.

You don’t need unique keys. Some paths with unique_key in the parameter’s name only work with the hash id. For example, listing an order’s invoices or shipments with its unique key returns an empty list:

GET List the invoices of a sales order /v2/api/store/{team_slug}/v2/sales_order/{unique_key}/invoice

Use the id field and you’ll never hit this.

Document numbers

The numbers on orders, invoices and other documents (scoped_id) are what people see in the web app and on PDFs, such as sales order SO1001. They aren’t ids:

• A path with a document number answers 404.
• Numbers can be edited, for example an invoice’s or a job’s, so they aren’t a stable reference.
• Jobs and shipments show their number with a prefix, such as JOB-7 and SHIP-45.

Find a record by its number

To turn a sales order or quote number into its id, search for it:

GET Search sales orders and quotes /v2/api/store/{team_slug}/search/orders

curl "https://secure.yoprint.com/v2/api/store/your-team/search/orders?q=SO1001" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json" \
  -H "X-Yoprint-Decimal-Format: exact-v1"

The search matches order numbers, order names, customer PO numbers, customer names and any part of the addresses, and returns up to 30 matches. Pick the one whose scoped_id is exactly the number you want, then use its id.

Catalog product ids

Products from a supplier catalog have their own ids, which start with the supplier’s code and a hyphen, such as smr-10001. You send them as text where an operation asks for a catalog product, for example in a catalog product line item.