Create or replace an order

Use this endpoint for platform: "custom" orders. It creates the
order on the first call and replaces it on later calls, and is the
recommended way to send custom-platform orders.

  • 201 on first create — data.newly_created: true,
    data.applied: true, plus protect_order_number and
    order_number.
  • 200 with data.applied: true and data.fields_changed_count
    when the request body differs from the stored order.
  • 200 with data.applied: false and data.reason: "no_change"
    when the request body matches the stored order.

The path identifies the order

The path parameter order_number identifies the order. If the
body also supplies order_number, it must match the path; otherwise
the request fails with 422 PATH_BODY_MISMATCH. You may omit
order_number from the body — the path value populates it.

Fields that cannot change after the first create

These fields are set on the first create and cannot be changed by a
later request: platform, order_number, order_id,
protect_order_number, is_protected, order_date_created,
platform_domain, source_channel, api_version, and
order_lifecycle_status. On later requests, send the same values or
omit them — both are accepted.

Server-injected fields

store_id, platform_domain, currency, source_channel, and
api_version are server-injected from the JWT-derived Store
record. Client values for these fields are silently dropped.

Line-item identity across updates

line_items is replaced wholesale on every applied change, so the body
MUST contain the full, current set of lines. Get Plus owns a read-only
line_id per line — the stable key returns are filed against (the
line_id used by POST /returns).

  • On the first create you MAY supply your own line_id on each line.
    It's honoured only when every line carries a non-empty, order-unique
    line_id (then line_id_source: partner); otherwise Get Plus mints
    li_<hex> ids for all lines (line_id_source: protectplus).
  • On every later update Get Plus carries the id forward: a line
    that still matches an existing line (by product_id/sku) keeps its
    line_id; only new lines get a new id. A line_id sent on an update
    is ignored — the id is fixed at create. Removing a line, or
    swapping the product/sku on a line, drops/replaces that line's id —
    so prefer quantity edits over re-keying a line you may still receive
    returns for.

Guard: if an update would remove or re-key a line that already has
a return request, the request is rejected with 409
(code: LINE_HAS_ACTIVE_RETURN) and the offending lines are listed
under line_items. Adjust quantities instead, or leave the line in
place. (Lines without returns can be removed/changed freely.)

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Path Params
string
required
length ≥ 1

The authoritative store order number. If the body supplies order_number, it must match this value.

Body Params

Request body for PUT /orders/{order_number} — create or replace an order on the custom platform.

  • platform must be "custom". Shopify and WooCommerce orders are ingested through their respective webhook paths.
  • order_number is optional. If supplied, it must match the URL path parameter; the path value is authoritative.
  • store_id, platform_domain, currency, source_channel, and api_version are server-injected. Any client values for these fields are silently dropped.
  • The top-level object is closed (additionalProperties: false); unknown keys are rejected with HTTP 422 (application/problem+json, VALIDATION_ERROR).

All timestamps are ISO 8601 / RFC 3339 in UTC. Monetary fields are decimal values with an ISO 4217 currency. Identifiers are opaque strings — do not parse them. Supply an Idempotency-Key (UUID) request header to make a retried PUT safe.

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 from the Store record.

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

Set on first create only; later requests to the same order cannot change this field.

line_items
array of objects
required
length between 1 and 250
line_items*
string
length ≤ 32
metadata
object
string
length ≤ 4096
string
length between 1 and 128

Optional source-platform internal order ID.

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. PUT /orders is a FULL REPLACE — resend order_notifications on every request to keep it; omitting it clears the stored opt-in.

string
length between 1 and 128

Optional. If supplied MUST equal the URL path order_number; otherwise the path value populates this field on the persisted doc.

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 order placement timestamp (UTC).

string
enum
required

Must be "custom" (Shopify / WooCommerce continue to use webhook ingestion). Stored as canonical Pascal-case Custom.

Allowed:
string

Ignored if supplied by the client — server-injected from the Store record.

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
string
length ≤ 64
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

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