Developers
API reference
REST over HTTPS with JSON. Every request carries an app token, and the token determines the store.
API reference
- Base URL
https://api.saleya.app/v1- Version
- 1
- Authentication
- App token from the store settings, sent as Authorization: Bearer <token>.
- Specification
The API names these addresses itself: a GET to the base URL or to the root of its host needs no token and returns the addresses of this reference, the OpenAPI file and the Postman collection; the first two also come in its Link header (RFC 8631).
Scopes
An app gets only the scopes the store chose for it. A write scope includes the read scope of its resource, and a request without the scope of its endpoint gets 403 insufficient_scope.
| Scope | In the store admin | What it grants | Endpoints |
|---|---|---|---|
catalog:read | Catalog — Read | Read the catalog: categories, products with their variants and photos, recommendation rules, location price lists with fixed prices and surcharges. | |
catalog:write | Catalog — Write | Create, change and archive categories, products, variants, product options and photos, and recommendation rules; set the rule, fixed prices and surcharges of location price lists; follow photo downloads. Includes catalog:read | |
inventory:read | Stock — Read | Read stock levels by location, the stock movement ledger, lots, location transfers, stock counts and the write-off reasons of the store. | |
inventory:write | Stock — Write | Set the on-hand quantity after a count, receive stock and write it off. Includes inventory:read | |
orders:read | Orders — Read | Read orders, draft orders, order statuses, delivery methods and manual payment methods. Customer contacts in orders also need customers:read. | |
orders:write | Orders — Write | Create and place draft orders, move orders between statuses, cancel them and issue their carrier shipments, and write the tracking number of a delivery service without integration. Placing a draft as paid also needs payments:write, cancelling an order with money received — refunds:write. Includes orders:read | |
orders:wholesale | Orders — Wholesale price lists | Wholesale terms — the dashboard permission to run wholesale: create, change and delete wholesale price lists, their fixed prices and surcharges, and assign a wholesale price list to a customer (with customers:write). Includes orders:read, catalog:read and costs:read: a wholesale list prices from cost. Wholesale sales are not available through the API. Includes orders:read, catalog:read, costs:read | |
customers:read | Customers — Read | Read customers with their address books, tax details and groups, and see the customer contacts, address and comment in orders and the recipient of fiscal documents. Adds fields to orders:read, fiscal:read | |
customers:write | Customers — Write | Create and change customers, their address books and tax details; manage customer groups and their members. Includes customers:read | |
locations:read | Locations — Read | Read the store locations the app has access to. | |
payments:read | Payments — Read | Read the payments of orders. | |
payments:write | Payments — Write | Confirm a manual payment as received and place a draft order as paid. Includes payments:read | |
refunds:read | Refunds — Read | Read the refunds of orders. | |
refunds:write | Refunds — Write | Calculate and create refunds, confirm manual payouts and cancel orders with money received. Includes refunds:read | |
costs:read | Costs — Read | Add cost prices to catalog variants and order items and show wholesale price lists, which price from cost. Opens no endpoints of its own and works only together with catalog:read or orders:read. Adds fields to catalog:read, orders:read | |
fiscal:read | Accounting — Read | Read the store legal entities, fiscal documents with their PDFs, tax periods, and withholdings and perceptions with the store certificates. The document recipient also requires customers:read. Together with orders:read it adds the external POS document to orders. Adds fields to orders:read | |
fiscal:write | Accounting — Write | Issue the invoice of a closed sale, reissue a document after a failure or a rejection by the tax authority and dismiss a rejected document. Issuing goes to the tax authority: the idempotency key is required. Includes fiscal:read | |
fiscal:annul | Accounting — Invoice annulment | Annul issued invoices with a credit note. Irreversible: the note stays with the tax authority. Grants no writes: issuing documents and annulling them are separate permissions. Includes fiscal:read | |
finance:read | Money — Read | Read money accounts with balances, categories, the money journal with source and primary document, the accounting day rate, register shifts with drawer reconciliation and the cash drawer journal, gift cards with the store liability and their activity, and customer accounts in the receivables book with their entries and statement. | |
finance:write | Money — Write | Record manual income and expenses, update and delete them, transfer between accounts, categorize the journal in bulk and record customer debt payments with money already received. Accounts and categories are managed in the store panel. Includes finance:read | |
procurement:read | Procurement — Read | Read suppliers with tax details and payment terms, supplier bills with tax, lines and amount due, bill payments, supplier balances, statements, offsets, purchase orders, goods receipts, supplier returns and consignment settlements. | |
procurement:write | Procurement — Write | Create and change suppliers: tax details, payment terms and external ID. Purchase orders: draft, change, place, cancel and close. Supplier bills: draft, change, delete the draft, post and void. Includes procurement:read | |
procurement:approve | Procurement — Approve bills for payment | Approve posted supplier bills for payment and revoke the approval: an unapproved bill cannot be paid. Grants no write access: entering bills and authorising their payment are separate powers. Includes procurement:read | |
procurement:pay | Procurement — Pay supplier bills | Pay approved supplier bills outside the system — when the money left outside the store's accounts, for example from the ERP's bank — and cancel a payment. Grants neither write access nor approval: entering bills, authorising their payment and paying them are separate powers. Includes procurement:read | |
webhooks:read | Webhooks and events — Read | Read the event feed, webhook endpoints and their deliveries. | |
webhooks:write | Webhooks and events — Write | Create, change and delete webhook endpoints, get and rotate their secrets, send test events and retry deliveries. Includes webhooks:read | |
bulk:read | Bulk operations — Read | Read bulk operations, download their results and check uploads. | |
bulk:write | Bulk operations — Write | Upload files, start and cancel bulk operations. Each operation type also needs the scope of its resource. Includes bulk:read |
Limits
Ceilings and retention periods of the API. The rate limits of the plan come in the RateLimit-Policy header of every response.
| Limit | Value |
|---|---|
| Records on a page of a list (limit). | 250 records |
| Current tokens of an app: one in use and one being rolled out. | 2 |
| How long the response to a request with an Idempotency-Key is kept. | 24 hours |
| How long a sync cursor stays valid; an older one gets 410 cursor_expired. | 30 days |
| How long events are kept in GET /v1/events. | 30 days |
| How long requests stay in the request log of the app. | 30 days |
| Webhook endpoints of an app. | 10 |
| How long a webhook delivery waits for the response of the endpoint. | 10 seconds |
| How long the previous secret keeps signing after a rotation. | 24 hours |
| Automatic retries of a failed webhook delivery. | 10 |
| About how long the automatic retries of a delivery last. | 72 hours |
| How long an endpoint may fail without a single success before it is disabled. | 72 hours |
| Bulk operations of an app waiting or running at the same time. | 5 |
| Size of the input file of a bulk operation. | 256 MB |
| Size of one line of the input. | 1 MB |
| Size of one chunk of an upload. | 1 MB |
| How long a finished bulk operation and its files are kept. | 7 days |
| Requests a minute from one address that may be rejected on entry (401, 403) before the address gets 429. | 60 |
Resources
Basics
App and token
Who the token speaks for: the app, its scopes, locations and rate limits. The first call of an integration: it shows the token works and which scopes it lacks.
Store
What every other response is read with: the currency of money amounts, the time zone of calendar dates and the languages of the content.
Locations
Locations of the store: shops, warehouses, kitchens and pickup points. Stock, orders and pickup refer to them.
Catalog
Categories
Catalog categories as a flat list: the tree is built by parent_id. Created, changed, archived and matched by external ID.
Products
Product cards: names, descriptions, categories, options and photos. Variants have their own endpoints; a product is created and written together with them.
- getList products: categories, options and media, without variants
- postCreate a product with its variants
- getGet a product
- patchChange a product card: fields, categories, external ID
- deleteArchive a product with its variants
- getGet a product by its external ID
- patchCreate or update a product with its variants by its external ID
- putReplace the product options and lay out its variants
Variants
What is actually sold and stocked: SKU, barcodes, prices, the unit and how it is sold. Variants change under the version of their product card.
- getList product variants: SKU, barcodes, prices and units
- postAdd a variant to a product
- getGet a product variant
- patchUpdate a product variant
- deleteArchive a product variant
- getGet a product variant by its external ID
- patchCreate or update a variant by its external ID
- getGet the recipe of a variant: components and the yield of a prep
- putReplace the recipe of a variant: components and the yield of a prep
Product photos
The gallery of a product: add a photo by URL, reorder, choose the main one, remove.
Photo downloads
Photos added by URL are downloaded in the background; a download shows its status and the reason of a failure.
Modifier groups
Choices for an item: sauces, extras, portion size. The group sets the selection bounds, options set surcharge and composition.
- getList modifier groups with options changed since the given moment
- postCreate a modifier group with options
- getGet a modifier group with its options
- patchUpdate a modifier group and its option set
- deleteArchive a modifier group
- getGet a modifier group by external ID
- patchCreate or update a modifier group by external ID
Product modifiers
Which modifier groups a product has, in order, with its selection rule and option surcharges by variant.
Recommendation rules
What to offer next to the products of a category or collection, by priority: the own list of the product, then rules top to bottom, then automatic picks.
Tax classes
Tax classes of the store that products refer to by tax_class_id: the kind of tax and its rate, which each sale keeps.
Price lists
Location and wholesale price lists: a percentage over the base price or over cost, with rounding. Fixed prices and surcharges have their own feeds.
- getList the store's price lists: location and wholesale lists with their rule and rounding
- postCreate a wholesale price list
- getGet a price list
- patchUpdate a price list: adjustment and rounding, and the name of a wholesale list; a location list's rule changes prices at all its locations
- deleteDelete a wholesale price list; its assignment to customers is removed with consent
Price list fixed prices
Fixed variant prices in price lists that override the list rule: the price in the price list currency and in store money.
Price list fixed surcharges
Fixed modifier option surcharges in price lists: for one variant of the item or for all, in the price list currency and in store money.
Inventory
Stock
Stock of a variant at a location: read the levels, set the on-hand quantity after a count, receive or write off goods.
Stock movements
Journal of a location's physical stock: sales, receipts, write-offs, stocktakes, transfers and their reversals. Append-only.
Lots
Product lots: number from the package, expiry date and availability. Stock movements and document lines point to the lot.
Location transfers
Transfers of goods between store locations: a posted document with lines. A mistake is undone by a reverse transfer.
Stock counts
Stock counts of a location: coverage, blind counting and status from draft to posted. Lines come in a feed of their own.
Stock count lines
What a count found: expected and counted quantity per item and lot, the variance, the adjustment applied and the location on-hand after posting.
Write-off reasons
Reasons of the store a write-off names: the reason decides the accounting kind and whether a comment is needed.
Orders and payments
Orders
Orders of every channel: items, totals, status and payment. The feed returns changes in commit order; status changes follow the rules of the store.
- getList orders changed since a given time: items, totals, the order status and the payment status
- getGet an order
- getDownload the carrier label of the order's current shipment as a PDF; it carries the recipient's details, so customers:read is required too
- postMove an order to another status of the store
- postCancel an order
- postIssue the order's shipment with its carrier: the request runs in the background, the outcome shows in the order and arrives with order.updated
- postWrite the tracking number of a delivery service without integration: number, link and service name
- postRemove a manually written tracking number
Order statuses
Status list of the store with its own statuses, the lasting meaning of each and the allowed transitions.
Draft orders
An order prepared by the app: priced live by the catalog, discounts and delivery, it shows what prevents placing it and becomes an order on completion.
Payments
Payment attempts of orders and their outcome. Manual payments waiting for money are confirmed here.
Refunds
Refunds of orders: calculate first, then refund items and delivery; the money goes back by the payment methods, the goods go back to stock.
- getList order refunds changed since a given time: items and payment transactions
- getGet an order refund
- postCalculate an order refund and what is left to refund, without writing anything
- postRefund order items and delivery: money goes back by the payment methods, goods go back to stock
- postConfirm that the refund money was paid back outside the system
Delivery methods
Delivery methods of the store: the list that orders and draft orders refer to by delivery_method_id.
Manual payment methods
Manual payment methods of the store, such as a bank transfer, that orders and payments refer to.
Customers
Customers
Customers of the store with their contacts, marketing consent and address book. All of it is personal data under the customers:read scope.
- getList customers changed since a given time: contacts, marketing consent, addresses and groups; look up by phone, email and group
- postCreate a customer: a name and at least one contact
- getGet a customer
- patchUpdate a customer's name, language and external ID
- getGet a customer by its external ID
- patchCreate or update a customer by its external ID
- postAssign a wholesale price list to a customer or remove it
Customer addresses
The address book of a customer: add, change, make the main one, delete.
Customer tax details
Tax details of a customer: receipts and invoices of new orders of the customer are issued under them.
Customer groups
Manual customer groups that discounts and broadcasts target: VIP, wholesale, staff. Membership is the group_ids field of a customer.
- getList the store's customer groups: name, description and whether they are active
- postCreate a customer group
- getGet a customer group
- patchChange a group's name, description or activity
- deleteDelete a group: its memberships go with it, and discount rules and broadcasts stop targeting it
- postAdd customers to a group
- postRemove customers from a group
Accounting
Legal entities
The store legal entities: tax ID and tax status, issuers of fiscal documents. Fiscal documents and tax periods refer to them.
Fiscal documents
Sales invoices, credit and debit notes as the tax authority issued them: number, date, tax, annulment and PDF.
- getList fiscal documents changed since a given moment: invoices, credit and debit notes in every status
- getGet a fiscal document
- getDownload the PDF of a fiscal document, the same file the customer receives
- postIssue the invoice of a closed sale: issuing runs in the background, the outcome comes as an event
- postReissue a document after a failure or a rejection by the tax authority
- postDismiss a rejected document: it will not be issued
- postAnnul an issued invoice with a credit note
Tax periods
Tax accounting months of legal entities: a closed period is filed, and its data no longer changes. Argentine stores only.
Withholdings and perceptions
Tax withheld from the store, which it credits, and tax the store withheld from suppliers, which it remits; the store certificates in PDF.
Money accounts
Accounts where the store money comes in and goes out: cash, bank, acquiring, wallet. The balance is in the account currency.
Money categories
Tree of income and expense categories. A system category is identified by system_code, not by its name.
Money transactions
Journal of income and expenses by account: posting amount, posting record and primary document.
- getList money transactions changed since a given moment: account income and expenses with their source and primary document
- postRecord manual income or expense on a money account
- getGet a money transaction
- patchUpdate a money transaction: only the category, counterparty and description of a transaction with a source document
- deleteDelete a manual money transaction and restore the account balance
Transfers between accounts
Money transfer from one account to another with a fee: create, update and delete. Transfer legs are money transactions with transfer_id.
Accounting day rates
Rate of a currency to the store currency on a date, used by the money journal for foreign-currency accounts; for revaluation and reconciliation.
Register shifts
Register shifts with cash drawer reconciliation for each currency: opening float, expected, counted, difference and float left behind.
Cash drawer movements
The shift drawer journal: cash sales and refunds, pay-ins, pay-outs, safe drops, change and reversals. Append-only.
Pay-in and pay-out reasons
Reasons that name a cash pay-in or pay-out from the drawer, with the category the money journal posts the movement to.
Gift cards
The store gift cards: face value, balance and the store liability for each card. The card code is not stored or returned.
Gift card activity
Gift card activity entries: issue, redemption, refund to the card, adjustment, void and block. Append-only.
Customer accounts
The store receivables book: each customer balance, credit limit, payment terms and a statement for a period with due dates.
- getCustomer accounts in the receivables book: balance, credit limit and payment terms
- getCustomer account
- getCustomer account statement for a period: opening and closing balance, entries with a running balance, and open debts with due dates
- postRecord a customer debt payment with money already received: an entry in the receivables book with withholding certificates
Customer account entries
Receivables book entries: sale on account, payment, return, write-off, offset, withholding and reversal. Append-only.
Procurement
Suppliers
Supplier directory: tax details, purchase currency, payment term and settlement mode, plus balance and statement. Contact person and notes are not exposed.
- getStore suppliers: tax details and payment terms
- postCreate a supplier: tax details and payment terms
- getSupplier
- patchUpdate a supplier's tax details, payment terms and external ID
- getSupplier by its external ID
- patchCreate or update a supplier by its external ID
- getSupplier balance: what the store owes right now, by component and due date
- getSupplier statement for a period: opening and closing balance, lines with a running balance
Supplier bills
Payables: invoices, debit and credit notes, debts for deliveries without an invoice — with VAT by rate, perceptions and lines.
- getSupplier bills: invoices, notes and debts for deliveries without an invoice, with tax and lines
- postCreate a draft supplier bill
- getSupplier bill
- patchChange a draft supplier bill
- deleteDelete a draft supplier bill
- postPost a supplier bill: it enters payables and the purchase ledger
- postVoid a supplier bill together with its payments and offsets
- postApprove a posted supplier bill for payment
- postRevoke the payment approval of a supplier bill
Supplier bill payments
What settled a supplier bill and by how much: money, offset, credit note, advance, journal expense or outside the system.
Offset agreements
The basis of an offset: parties, bilateral or three-party offset, contract number and date, term and the schedule of recurring offsets.
Offsets
An offset document: what a customer owes the store against what the store owes a supplier. A voided offset stays with status voided.
Offset lines
What exactly was offset: an order or the customer account debt and a supplier bill, with the settlements the offset created.
Purchase orders
What the store ordered from a supplier: lines with ordered, confirmed and received quantities, price and promised delivery date.
- getPurchase orders: ordered, confirmed by the supplier and received, by line
- postCreate a draft purchase order
- getPurchase order
- patchChange a purchase order: a draft in full, a placed order’s lines, date and note with a revision
- deleteDelete a draft purchase order
- postMark a draft as placed with the supplier
- postCancel a placed purchase order
- postClose a received purchase order
Goods receipts
Goods received from a supplier: lines with the delivery note price and cost, before-and-after corrections. A reversal sets voided_at.
Supplier returns
Goods shipped back to a supplier: lines and the expected and received compensation — a credit note, replacement goods or money.
Consignment settlements
Statements of consignment goods sold over a period, the basis of the supplier invoice: sections, lines and totals.
Bulk operations
Uploads
A large file sent in chunks: the server counts received bytes, so a broken upload continues from there. The input of a bulk operation.
Bulk operations
Thousands of records in one request: set stock, write products, export orders. The result is NDJSON, one line per input line, downloaded in ranges.
- getList the app bulk operations changed since a given time: progress and outcomes
- postStart a bulk operation from an upload or an input address, a feed export or a file build
- getGet a bulk operation
- getGet the result of a bulk operation — NDJSON, a line per input line or per exported item, or the ZIP of a file operation; resume with Range
- postCancel a bulk operation at a line boundary
Events and webhooks
Events
What changed in the store over the last 30 days, with the record as it is now. The same events go to webhook endpoints.
Webhook endpoints
Addresses the store sends events to, signed by Standard Webhooks; the signing secret, its rotation and a test event.
- getList the webhook endpoints of the app
- postAdd a webhook endpoint and subscribe it to event types
- getRetrieve a webhook endpoint
- patchUpdate a webhook endpoint: URL, description, event types, status
- deleteDelete a webhook endpoint
- postIssue a new signing secret: the previous one keeps signing deliveries alongside it for 24 hours
- getRetrieve the delivery signing secret of a webhook endpoint
Webhook deliveries
What went out to an endpoint, what waits for a retry and what failed, with the responses of the receiver; a delivery can be retried.
Parameters of every request
Accept-LanguagestringLanguage of error texts: es, en or ru. English by default.
- Example:
es
Headers of every successful response
RateLimitstringrequiredRequests left in a row and seconds until the bucket is full again, per policy.
- Example:
"app";r=87;t=3, "store";r=390;t=1
RateLimit-PolicystringrequiredRate limit policies: quota per window in seconds.
- Example:
"app";q=300;w=60, "store";q=1200;w=60
X-Request-IdstringrequiredRequest ID. Quote it when you contact support.
Errors
Errors come as application/problem+json (RFC 9457). type is a stable code to branch on; title and detail are text for people, in the language of Accept-Language.
Error types
| Status | Type | What happened |
|---|---|---|
| 401 | api_token_expired | API token has expired |
| 401 | api_token_invalid | API token is not valid |
| 401 | api_token_missing | API token required |
| 401 | api_token_revoked | API token has been revoked |
| 403 | capability_disabled | Resource not available to this store |
| 403 | forbidden | Forbidden |
| 403 | insufficient_scope | Scope is missing |
| 403 | integration_api_not_in_plan | Integration API is not in the plan |
| 403 | ip_not_allowed | Address is not allowed |
| 404 | not_found | Not found |
| 405 | method_not_allowed | Method not allowed |
| 409 | address_book_full | The customer's address book is full |
| 409 | bulk_operation_finished | The operation has already finished |
| 409 | bulk_operation_queue_full | The app operation queue is full |
| 409 | bulk_operation_result_unavailable | There is no result file |
| 409 | consent_required | Consent to the consequences is required |
| 409 | customer_contact_in_use | The contact already belongs to a store customer |
| 409 | draft_order_closed | The draft order is closed |
| 409 | external_id_archived | The record with this external ID is archived |
| 409 | external_id_in_use | The external ID is taken |
| 409 | fiscal_document_annul_refused | The invoice can't be annulled |
| 409 | fiscal_document_dismiss_refused | The document can't be dismissed |
| 409 | fiscal_document_pdf_unavailable | Document has no file |
| 409 | fiscal_document_reissue_refused | The document can't be reissued |
| 409 | idempotency_key_in_use | A request with this key is in progress |
| 409 | in_use_conflict | Record in use |
| 409 | invoice_issue_refused | The order invoice can't be issued now |
| 409 | money_transaction_locked | The transaction cannot be changed by hand |
| 409 | order_cancel_refused | The order cannot be cancelled |
| 409 | order_transition_refused | The order cannot move to this status |
| 409 | payment_not_confirmable | The payment cannot be confirmed |
| 409 | plan_limit_reached | The plan limit is reached |
| 409 | purchase_order_refused | The purchase order does not accept this command |
| 409 | record_limit_reached | The record limit is reached |
| 409 | refund_not_confirmable | The refund does not await a payout confirmation |
| 409 | refund_refused | The order cannot be refunded |
| 409 | shipment_in_progress | A shipment issue is already under way |
| 409 | shipment_label_unavailable | No shipping label |
| 409 | shipment_outcome_unknown | The previous issue has an unknown outcome |
| 409 | shipment_refused | The shipment cannot be issued now |
| 409 | shipment_tracking_refused | The tracking number can't be written manually |
| 409 | stock_held_by_write_offs | Stock is held by write-offs awaiting approval |
| 409 | stock_on_hand_changed | On-hand quantity changed |
| 409 | supplier_bill_payment_locked | The bill payment cannot be cancelled directly |
| 409 | supplier_bill_refused | The supplier bill does not accept this command |
| 409 | tax_withholding_certificate_unavailable | Record has no certificate |
| 409 | unique_conflict | Duplicate value |
| 409 | upload_offset_mismatch | The chunk does not start where expected |
| 409 | webhook_endpoint_limit_reached | The app has the maximum number of webhook endpoints |
| 410 | cursor_expired | Sync cursor expired |
| 412 | precondition_failed | The record has changed |
| 416 | range_not_satisfiable | The range starts beyond the result |
| 422 | idempotency_key_required | Idempotency key is required |
| 422 | idempotency_key_reused | Idempotency key is already used |
| 422 | invalid_idempotency_key | Idempotency key is invalid |
| 422 | last_variant_of_product | Last variant of the product |
| 422 | money_out_of_range | Amount out of range |
| 422 | validation_error | Invalid request |
| 428 | precondition_required | If-Match is required |
| 429 | too_many_requests | Too many requests |
| 500 | server_error | Server error |
| 503 | carrier_unavailable | Carrier unavailable |
| 503 | store_frozen | Store frozen |
| 503 | transient_conflict | Temporary conflict |
| depends on the request | http_error | HTTP error |
Error bodies
Problem
typestringrequiredMachine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.
titlestringrequiredShort summary of the problem in the language of the request.
statusintegerrequiredHTTP status of the response.
detailstringExplanation of this occurrence in the language of the request.
ForbiddenProblem
typestringrequiredMachine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.
titlestringrequiredShort summary of the problem in the language of the request.
statusintegerrequiredHTTP status of the response.
detailstringExplanation of this occurrence in the language of the request.
required_scopestringFor insufficient_scope — the scope the endpoint needs.
accepted_scopesarray of stringFor insufficient_scope — the scopes the endpoint accepts: any one is enough. For an endpoint with one scope — that scope alone.
ValidationProblem
typestringrequiredMachine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.
titlestringrequiredShort summary of the problem in the language of the request.
statusintegerrequiredHTTP status of the response.
detailstringExplanation of this occurrence in the language of the request.
errorsmap of array of stringrequiredInvalid fields: name of the field (nested ones with dots, such as variants.0.price) → messages.
RateLimitProblem
typestringrequiredMachine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.
titlestringrequiredShort summary of the problem in the language of the request.
statusintegerrequiredHTTP status of the response.
detailstringExplanation of this occurrence in the language of the request.
policystringrequiredWhich bucket ran out: app — of the app; store — of the store, shared by all its apps; rejected — of requests from one address that were rejected on entry.
- Values:
appstorerejected
ConflictProblem
typestringrequiredMachine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.
titlestringrequiredShort summary of the problem in the language of the request.
statusintegerrequiredHTTP status of the response.
detailstringExplanation of this occurrence in the language of the request.
currentobjectThe record as it is now, the fields the conflict is about: on_hand for stock_on_hand_changed, status for rejected order changes, status and order_id for a closed draft.
external_idstringFor external_id_in_use and external_id_archived — the taken external ID.
consent_kindstringFor consent_required — the kind of consequence to agree to.
consequencesmap of integerFor consent_required — what will change: kind of data → number of records.
- Minimum:
- 0
consent_tokenstringFor consent_required — fingerprint of the shown consequences. Repeat the request with consent[<consent_kind>]=<consent_token>.
variant_idintegerFor consent_required of a variant line in a product write — the variant: the consent is given by changing that variant (PATCH /v1/variants/{variant}).
limitintegerFor plan_limit_reached, address_book_full, bulk_operation_queue_full and webhook_endpoint_limit_reached — the limit.
- Minimum:
- 0
fieldstringFor customer_contact_in_use — the contact that belongs to another customer: phone or email.
- Values:
phoneemail
existing_customer_idintegerFor customer_contact_in_use — the customer the contact belongs to.
receivedintegerFor upload_offset_mismatch — bytes the upload has received: the offset to continue from.
- Minimum:
- 0
operation_statusstringFor bulk_operation_finished — the status the operation finished with.