Developers

API reference

REST over HTTPS with JSON. Every request carries an app token, and the token determines the store.

Loading the search index…

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.

ScopeIn the store adminWhat it grantsEndpoints
catalog:readCatalog — ReadRead the catalog: categories, products with their variants and photos, recommendation rules, location price lists with fixed prices and surcharges.
catalog:writeCatalog — WriteCreate, 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:readStock — ReadRead stock levels by location, the stock movement ledger, lots, location transfers, stock counts and the write-off reasons of the store.
inventory:writeStock — WriteSet the on-hand quantity after a count, receive stock and write it off. Includes inventory:read
orders:readOrders — ReadRead orders, draft orders, order statuses, delivery methods and manual payment methods. Customer contacts in orders also need customers:read.
orders:writeOrders — WriteCreate 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:wholesaleOrders — Wholesale price listsWholesale 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:readCustomers — ReadRead 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:writeCustomers — WriteCreate and change customers, their address books and tax details; manage customer groups and their members. Includes customers:read
locations:readLocations — ReadRead the store locations the app has access to.
payments:readPayments — ReadRead the payments of orders.
payments:writePayments — WriteConfirm a manual payment as received and place a draft order as paid. Includes payments:read
refunds:readRefunds — ReadRead the refunds of orders.
refunds:writeRefunds — WriteCalculate and create refunds, confirm manual payouts and cancel orders with money received. Includes refunds:read
costs:readCosts — ReadAdd 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:readAccounting — ReadRead 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:writeAccounting — WriteIssue 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:annulAccounting — Invoice annulmentAnnul 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:readMoney — ReadRead 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:writeMoney — WriteRecord 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:readProcurement — ReadRead 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:writeProcurement — WriteCreate 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:approveProcurement — Approve bills for paymentApprove 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:payProcurement — Pay supplier billsPay 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:readWebhooks and events — ReadRead the event feed, webhook endpoints and their deliveries.
webhooks:writeWebhooks and events — WriteCreate, change and delete webhook endpoints, get and rotate their secrets, send test events and retry deliveries. Includes webhooks:read
bulk:readBulk operations — ReadRead bulk operations, download their results and check uploads.
bulk:writeBulk operations — WriteUpload 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.

LimitValue
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

Catalog

Inventory

Orders and payments

Customers

Accounting

Procurement

Parameters of every request

  • Accept-Languagestring

    Language of error texts: es, en or ru. English by default.

    Example:
    es

Headers of every successful response

  • RateLimitstringrequired

    Requests 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-Policystringrequired

    Rate limit policies: quota per window in seconds.

    Example:
    "app";q=300;w=60, "store";q=1200;w=60
  • X-Request-Idstringrequired

    Request 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

StatusTypeWhat happened
401api_token_expiredAPI token has expired
401api_token_invalidAPI token is not valid
401api_token_missingAPI token required
401api_token_revokedAPI token has been revoked
403capability_disabledResource not available to this store
403forbiddenForbidden
403insufficient_scopeScope is missing
403integration_api_not_in_planIntegration API is not in the plan
403ip_not_allowedAddress is not allowed
404not_foundNot found
405method_not_allowedMethod not allowed
409address_book_fullThe customer's address book is full
409bulk_operation_finishedThe operation has already finished
409bulk_operation_queue_fullThe app operation queue is full
409bulk_operation_result_unavailableThere is no result file
409consent_requiredConsent to the consequences is required
409customer_contact_in_useThe contact already belongs to a store customer
409draft_order_closedThe draft order is closed
409external_id_archivedThe record with this external ID is archived
409external_id_in_useThe external ID is taken
409fiscal_document_annul_refusedThe invoice can't be annulled
409fiscal_document_dismiss_refusedThe document can't be dismissed
409fiscal_document_pdf_unavailableDocument has no file
409fiscal_document_reissue_refusedThe document can't be reissued
409idempotency_key_in_useA request with this key is in progress
409in_use_conflictRecord in use
409invoice_issue_refusedThe order invoice can't be issued now
409money_transaction_lockedThe transaction cannot be changed by hand
409order_cancel_refusedThe order cannot be cancelled
409order_transition_refusedThe order cannot move to this status
409payment_not_confirmableThe payment cannot be confirmed
409plan_limit_reachedThe plan limit is reached
409purchase_order_refusedThe purchase order does not accept this command
409record_limit_reachedThe record limit is reached
409refund_not_confirmableThe refund does not await a payout confirmation
409refund_refusedThe order cannot be refunded
409shipment_in_progressA shipment issue is already under way
409shipment_label_unavailableNo shipping label
409shipment_outcome_unknownThe previous issue has an unknown outcome
409shipment_refusedThe shipment cannot be issued now
409shipment_tracking_refusedThe tracking number can't be written manually
409stock_held_by_write_offsStock is held by write-offs awaiting approval
409stock_on_hand_changedOn-hand quantity changed
409supplier_bill_payment_lockedThe bill payment cannot be cancelled directly
409supplier_bill_refusedThe supplier bill does not accept this command
409tax_withholding_certificate_unavailableRecord has no certificate
409unique_conflictDuplicate value
409upload_offset_mismatchThe chunk does not start where expected
409webhook_endpoint_limit_reachedThe app has the maximum number of webhook endpoints
410cursor_expiredSync cursor expired
412precondition_failedThe record has changed
416range_not_satisfiableThe range starts beyond the result
422idempotency_key_requiredIdempotency key is required
422idempotency_key_reusedIdempotency key is already used
422invalid_idempotency_keyIdempotency key is invalid
422last_variant_of_productLast variant of the product
422money_out_of_rangeAmount out of range
422validation_errorInvalid request
428precondition_requiredIf-Match is required
429too_many_requestsToo many requests
500server_errorServer error
503carrier_unavailableCarrier unavailable
503store_frozenStore frozen
503transient_conflictTemporary conflict
depends on the requesthttp_errorHTTP error

Error bodies

Problem

  • typestringrequired

    Machine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.

  • titlestringrequired

    Short summary of the problem in the language of the request.

  • statusintegerrequired

    HTTP status of the response.

  • detailstring

    Explanation of this occurrence in the language of the request.

ForbiddenProblem

  • typestringrequired

    Machine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.

  • titlestringrequired

    Short summary of the problem in the language of the request.

  • statusintegerrequired

    HTTP status of the response.

  • detailstring

    Explanation of this occurrence in the language of the request.

  • required_scopestring

    For insufficient_scope — the scope the endpoint needs.

  • accepted_scopesarray of string

    For insufficient_scope — the scopes the endpoint accepts: any one is enough. For an endpoint with one scope — that scope alone.

ValidationProblem

  • typestringrequired

    Machine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.

  • titlestringrequired

    Short summary of the problem in the language of the request.

  • statusintegerrequired

    HTTP status of the response.

  • detailstring

    Explanation of this occurrence in the language of the request.

  • errorsmap of array of stringrequired

    Invalid fields: name of the field (nested ones with dots, such as variants.0.price) → messages.

RateLimitProblem

  • typestringrequired

    Machine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.

  • titlestringrequired

    Short summary of the problem in the language of the request.

  • statusintegerrequired

    HTTP status of the response.

  • detailstring

    Explanation of this occurrence in the language of the request.

  • policystringrequired

    Which 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

  • typestringrequired

    Machine type of the problem: a stable code to branch on, such as insufficient_scope. Every type has a page in the error catalog.

  • titlestringrequired

    Short summary of the problem in the language of the request.

  • statusintegerrequired

    HTTP status of the response.

  • detailstring

    Explanation of this occurrence in the language of the request.

  • currentobject

    The 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_idstring

    For external_id_in_use and external_id_archived — the taken external ID.

  • consent_kindstring

    For consent_required — the kind of consequence to agree to.

  • consequencesmap of integer

    For consent_required — what will change: kind of data → number of records.

    Minimum:
    0
  • consent_tokenstring

    For consent_required — fingerprint of the shown consequences. Repeat the request with consent[<consent_kind>]=<consent_token>.

  • variant_idinteger

    For consent_required of a variant line in a product write — the variant: the consent is given by changing that variant (PATCH /v1/variants/{variant}).

  • limitinteger

    For plan_limit_reached, address_book_full, bulk_operation_queue_full and webhook_endpoint_limit_reached — the limit.

    Minimum:
    0
  • fieldstring

    For customer_contact_in_use — the contact that belongs to another customer: phone or email.

    Values:
    phoneemail
  • existing_customer_idinteger

    For customer_contact_in_use — the customer the contact belongs to.

  • receivedinteger

    For upload_offset_mismatch — bytes the upload has received: the offset to continue from.

    Minimum:
    0
  • operation_statusstring

    For bulk_operation_finished — the status the operation finished with.