Lookups | API reference

List payment methods

GET /payment-methods

Scope: orders.write

Payment methods that are active and usable in the shop of your API client. Use id as payment_method_id when sending orders: every method in this list is accepted, any other ID is rejected with payment_method_not_available (or unknown_payment_method if it is inactive).

The collective invoice is listed with requires_customer_approval: true. It is accepted only if the customer is approved for it, as in the shop checkout: by the customer setting, otherwise by the customer class. For a new customer, the default customer class of the shop decides. customer_class_ids, min_order_value and max_order_value are for your information; the order intake does not check them for other methods.

Example request

curl "https://shop.example.com/api/v1/payment-methods" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Responses

200 OK List of payment methods.

{
  "data": [
    {
      "id": 3,
      "name": "Invoice",
      "provider": "invoice",
      "customer_class_ids": [],
      "min_order_value": null,
      "max_order_value": null,
      "requires_customer_approval": false
    },
    {
      "id": 5,
      "name": "Prepayment",
      "provider": "prepayment",
      "customer_class_ids": [
        2
      ],
      "min_order_value": 10,
      "max_order_value": 5000,
      "requires_customer_approval": false
    },
    {
      "id": 9,
      "name": "Collective invoice",
      "provider": "collective_invoice",
      "customer_class_ids": [
        4
      ],
      "min_order_value": null,
      "max_order_value": null,
      "requires_customer_approval": true
    }
  ]
}

Response fields

Field	Type	Required	Description
`data[]`	array of object	required
`id`	integer	required	Value for `payment_method_id`.
`name`	string	required	Name shown to customers.
`provider`	string	required	Technical type of the payment method, for example `invoice`.
`customer_class_ids`	array of integer	required	Customer classes the payment method is limited to. Empty means available for all classes.
`min_order_value`	number \| null	required	Minimum order value, `null` if there is none.
`max_order_value`	number \| null	required	Maximum order value, `null` if there is none.
`requires_customer_approval`	boolean	required	`true` for the collective invoice: it is accepted only if the customer (or, for a new customer, the shop's default customer class) is approved for it. `false` for all other methods.

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}

403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope.

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}

404 Not Found The path does not exist, the API is not enabled on this system, the order does not belong to the shop of your API client, or the customer, address or label value is not known to your API client.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}

429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}

500 Internal Server Error An unexpected error occurred on our side. Retry later.

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.

List referrers

GET /referrers

Scope: orders.write

Referrers (order origins) that are active and assigned to the shop of your API client, sorted by name. Use id as referrer_id when sending orders.

Example request

curl "https://shop.example.com/api/v1/referrers" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Responses

200 OK List of referrers.

{
  "data": [
    {
      "id": 17,
      "name": "Example App"
    }
  ]
}

Response fields

Field	Type	Required	Description
`data[]`	array of object	required
`id`	integer	required	Value for `referrer_id`.
`name`	string	required

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}

403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope.

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}

404 Not Found The path does not exist, the API is not enabled on this system, the order does not belong to the shop of your API client, or the customer, address or label value is not known to your API client.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}

429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}

500 Internal Server Error An unexpected error occurred on our side. Retry later.

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.

List order statuses

GET /order-statuses

Scope: orders.write

All order statuses of the shop, sorted by position, then id. Use id as order_status_id when sending orders: every status in this list is accepted, including cancelled and shipped statuses. Any other ID is rejected with unknown_order_status.

system_status_id is the fixed process step the shop maps the status to (for example incoming order or cancelled); 0 means the status is not mapped to a process step. Status names and IDs are configured per shop and can differ between your test and live shop.

Example request

curl "https://shop.example.com/api/v1/order-statuses" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Accept: application/json"

Responses

200 OK List of order statuses.

{
  "data": [
    {
      "id": 1,
      "name": "Incoming order",
      "system_status_id": 2,
      "position": 1
    },
    {
      "id": 4,
      "name": "Payment received",
      "system_status_id": 3,
      "position": 2
    },
    {
      "id": 9,
      "name": "Cancelled",
      "system_status_id": 7,
      "position": 9
    }
  ]
}

Response fields

Field	Type	Required	Description
`data[]`	array of object	required
`id`	integer	required	Value for `order_status_id`.
`name`	string	required	Name of the status as named in the shop.
`system_status_id`	integer	required	Fixed process step the status is mapped to, `0` if none.
`position`	integer	required	Sort position in the shop.

Error responses

401 Unauthorized The API key is missing, malformed, wrong, paused, expired or revoked. The body is always the same and never names the reason.

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key.",
    "details": []
  }
}

403 Forbidden The API key is valid but lacks a scope this endpoint needs. details.required lists the scopes the endpoint requires, details.missing the ones your key lacks. Ask the shop operator to add the scope.

{
  "error": {
    "code": "insufficient_scope",
    "message": "The API key is missing a required scope.",
    "details": {
      "required": [
        "orders.write"
      ],
      "missing": [
        "orders.write"
      ]
    }
  }
}

404 Not Found The path does not exist, the API is not enabled on this system, the order does not belong to the shop of your API client, or the customer, address or label value is not known to your API client.

{
  "error": {
    "code": "not_found",
    "message": "The requested resource does not exist.",
    "details": []
  }
}

429 Too Many Requests Too many requests. Either your API client used up its requests per minute (message Too many requests., with all rate limit headers), or too many failed authentications came in a short time (message Too many authentication attempts., only Retry-After). Both carry the code rate_limited.

{
  "error": {
    "code": "rate_limited",
    "message": "Too many requests.",
    "details": []
  }
}

500 Internal Server Error An unexpected error occurred on our side. Retry later.

{
  "error": {
    "code": "server_error",
    "message": "An unexpected error occurred.",
    "details": []
  }
}

All error codes: error code reference.