API Reference

Create an order

post deprecated
https://api.protectplus.io/orders

Deprecated for platform: "custom". For custom-platform orders,
use PUT /orders/{order_number} instead. It creates or
updates an order and is safe to retry.

POST /orders continues to work unchanged for platform: shopify
and platform: woocommerce. Those ingestion paths are not
deprecated. OpenAPI cannot mark a deprecation that applies to only
one platform value, so the operation-level deprecated flag reflects
the custom-platform deprecation only — treat it as advisory if you
are integrating Shopify or WooCommerce.

Create a new order on Get Plus. Use this when your OMS or
e-commerce platform has produced an order and you want to
attach Get Plus coverage to it.

Order contract

This endpoint accepts the full order contract: a strict, closed
schema covering the order with a nested customer, amounts,
structured addresses, line items, shipments, discounts, and tax
lines. See
OrderCreateRequest
for the full shape.

Idempotency

The endpoint is idempotent: replaying the same
(store_id, order_number, order_id) tuple returns the existing
order with HTTP 200 and data.newly_created: false. The first
call gets HTTP 201 and data.newly_created: true.

Server-injected fields

Five fields are server-injected and dropped if sent by the
client: store_id, platform_domain, currency,
source_channel, api_version. See OrderCreateRequest for
details.

Order ingestion mode (HTTP 409)

This endpoint only accepts orders for stores in custom_api
ingestion mode. A store left on the default shopify_webhook mode
gets a 409 Conflict, so the same order isn't ingested twice (once
via webhook and once via this endpoint). Set the store's Order
ingestion mode in the Get Plus dashboard before pushing orders.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params

Request body for POST /orders.

Seven fields are required: platform, order_number, ordered_at, currency, customer, amounts, line_items. Everything else is optional, but send what you have.

Server-injected fields

Five fields are server-injected and cannot be set by the client: store_id, platform_domain, currency, source_channel, and api_version. Any client values for these fields are silently dropped before the request is processed:

  • store_id is derived from the store_id claim on your JWT (the JWT you obtained from POST /auth/v1/token). You do not send any header for this — the gateway reads it from the token.
  • platform_domain is taken from your store record (resolved from the JWT-derived store_id), so it stays in sync with dashboard updates without forcing a token refresh.
  • currency is taken from the Store record's configured currency. You must still send currency in the body (it is validated for shape) but the value reaching storage is the Store's.
  • source_channel is always "custom_api" on this endpoint.
  • api_version is always "v1".

Strict body

The top-level object is closed (additionalProperties: false) — unknown keys are rejected with HTTP 422 (application/problem+json). Free-form / source-platform data belongs in metadata (≤16 top-level keys, ≤8 KB recommended) or source_payload (≤32 KB recommended, opaque to Get Plus).

Backward compatibility (deprecated, removed in the next release)

For one release window only, the gateway accepts two legacy keys and rewrites them silently before validation: store_order_number → order_number and store_order_id → order_id. Other legacy keys are not rewritten — see the full migration table in the POST /orders operation description.

Idempotency

Replaying the same (store_id, order_number, order_id) tuple returns the existing order with HTTP 200 and data.newly_created: false. The first call gets HTTP 201 and data.newly_created: true. Independently, an Idempotency-Key request header (UUID) makes any retried POST /orders safe — a replay returns the original response verbatim.

All timestamps are ISO 8601 / RFC 3339 in UTC. Monetary fields are decimal values accompanied by an ISO 4217 currency. Identifiers (store_id, order_id, …) are opaque strings — do not parse them.

amounts
object
required
string

Ignored if supplied by the client — server-injected (currently always "v1").

billing_address
object
string
required
^[A-Z]{3}$

ISO 4217 currency code, uppercase. Server-injected: required in the request for validation, but the value reaching storage is the Store's configured currency.

customer
object
required
discounts
array of objects
length ≤ 100
discounts
boolean

True if Get Plus protection should be applied. When true, amounts.protection_cost should be greater than 0.

line_items
array of objects
required
length between 1 and 250
line_items*
string
length ≤ 32

BCP 47 locale tag (optional).

metadata
object

Free-form key-value object (≤16 top-level keys, ≤8 KB recommended). Total serialised size enforced by the body parser.

string
length ≤ 4096
string
length between 1 and 128

Source-platform internal order ID. Falls back to order_number upstream when omitted.

order_notifications
object

Customer's per-channel opt-in for order/tracking notifications. Get Plus sends a tracking email only when email is true and an SMS only when sms is true; omit a channel (or send false) to suppress it. Persisted on the order so notification delivery can honour the customer's preference.

string
required
length between 1 and 128

Customer-facing order number. This is the single canonical external order identifier across the API.

date-time

ISO 8601 / RFC 3339 timestamp (UTC) of when the order was last updated in your system. Stored on the order alongside the payload. Note: Get Plus also maintains its own record updatedAt (the time we last wrote the document), which is distinct from your source-system timestamp.

date-time
required

ISO 8601 / RFC 3339 timestamp (UTC) of when the order was placed on the source platform.

string
enum
required

Source platform identifier. Lowercase on the request; Get Plus stores the canonical Pascal-case (Shopify, Woocommerce, Custom) on the order.

Allowed:
string

Ignored if supplied by the client — server-injected from the authenticated session.

shipments
array of objects
length ≤ 100

Shipments to register for this order. Each entry is registered with the carrier and drives the customer tracking page + notifications — the same pipeline as POST /shipments, so no separate call is needed. Registration is idempotent per (store, tracking_number, order_number). Include more than one entry for a split order (shipped in several packages, even across carriers); each tracking number is tracked independently and shows only its own items.

shipments
shipping_address
object
string

Ignored if supplied by the client — server-injected (always "custom_api" for this endpoint).

source_payload
object

Verbatim copy of the original platform payload (opaque to Get Plus; retained for later reference). ≤32 KB recommended; size enforced by the body parser.

string
length ≤ 64

Free-form source-platform status string.

string

Ignored if supplied by the client — server-injected from the authenticated session.

tax_lines
array of objects
length ≤ 100
tax_lines
Headers
string
enum
Defaults to application/json

Generated from available response content types

Allowed:
Responses

Updated 3 months ago

Did this page help you?
Language
Credentials
Bearer
JWT
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json
application/problem+json

Updated 3 months ago

Did this page help you?