Skip to content

Create or update an order or invoice by its id in your system

PUT
/products/{productId}/sync/orders/{source}/{externalId}
curl --request PUT \
--url https://api.motenya.app/v1/products/example/sync/orders/erp/C-1042 \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "storeId": "example", "number": "example", "contactId": "example", "clientId": "example", "subscriptionId": "example", "periodStart": "2026-11-21T09:30:00Z", "periodEnd": "2026-11-21T09:30:00Z", "status": "pending", "statusRaw": "example", "paymentStatus": "unpaid", "paidAt": "2026-11-21T09:30:00Z", "dueAt": "2026-11-21T09:30:00Z", "currency": "RON", "subtotal": "149.90", "shipping": "149.90", "tax": "149.90", "discount": "149.90", "total": "149.90", "paymentMethod": "example", "billingAddress": { "label": "example", "line1": "example", "line2": "example", "city": "example", "region": "example", "postalCode": "example", "country": "example" }, "shippingAddress": { "label": "example", "line1": "example", "line2": "example", "city": "example", "region": "example", "postalCode": "example", "country": "example" }, "placedAt": "2026-11-21T09:30:00Z", "items": [ { "catalogItemId": "example", "catalogItemExternalId": "example", "sku": "example", "name": "example", "quantity": 1, "unitPrice": "149.90", "rowTotal": "149.90", "options": [ { "label": "example", "value": "example" } ] } ], "custom": "example", "storeExternalId": "example", "contactExternalId": "example", "clientExternalId": "example", "subscriptionExternalId": "example", "contactEmail": "example", "contactName": "example", "shipments": [ { "carrierCode": "example", "carrierName": "example", "trackingNumber": "example", "state": "pending", "deliveredAt": "2026-11-21T09:30:00Z", "externalId": "C-1042", "history": [ { "at": "2026-11-21T09:30:00Z", "status": "example", "location": "example" } ] } ], "documents": [ { "kind": "invoice", "number": "example", "amount": "149.90", "reason": "example", "issuedAt": "2026-11-21T09:30:00Z", "externalId": "C-1042" } ] }'

Idempotent: the first call creates it, later calls with the same source and external id update the fields sent. References to other records can use their ids in the same source (…ExternalId). A new external id first matches an order by number in the same store (or among orders without one). Send subscriptionExternalId for a subscription’s invoice, and paymentStatus/paidAt to record a payment. shipments and documents replace what this source sent before.

Requires crm:write.

productId
required
string
>= 1 characters <= 64 characters
source
required

The system the record comes from, named by you: e.g. magento2:casa-verde, stripe, erp.

string
/^[a-z0-9][a-z0-9._:-]{0,63}$/

Example

erp

The system the record comes from, named by you: e.g. magento2:casa-verde, stripe, erp.

externalId
required

The record’s id in that system.

string
>= 1 characters <= 128 characters

Example

C-1042

The record’s id in that system.

Media typeapplication/json
object
storeId

Required unless the order bills a subscription; null takes a subscription’s invoice out of its store.

string | null
>= 1 characters <= 64 characters
number

The order or invoice number; unique per store, or among orders without a store.

string | null
>= 1 characters <= 64 characters
contactId
string | null
>= 1 characters <= 64 characters
clientId
string | null
>= 1 characters <= 64 characters
subscriptionId

Makes the order a subscription’s invoice. On create, fills the customer, store, currency and a line for the plan unless given.

string | null
>= 1 characters <= 64 characters
periodStart

The billing period a subscription invoice covers.

string | null
<= 40 characters

Example

2026-11-21T09:30:00Z
periodEnd

ISO-8601 date-time, e.g. 2026-11-21T09:30:00Z.

string | null
<= 40 characters

Example

2026-11-21T09:30:00Z
status
string | null
Allowed values: pending processing on_hold shipped completed canceled refunded
statusRaw

The store’s own status code, kept as is.

string | null
<= 64 characters
paymentStatus

Null or omitted: not tracked, which counts as paid in lifetime value and revenue.

string | null
Allowed values: unpaid partially_paid paid refunded void
paidAt

Now, when paid without one; unpaid or void clears it.

string | null
<= 40 characters

Example

2026-11-21T09:30:00Z
dueAt

ISO-8601 date-time, e.g. 2026-11-21T09:30:00Z.

string | null
<= 40 characters

Example

2026-11-21T09:30:00Z
currency

Defaults to the subscription’s or the store’s currency.

string | null
>= 3 characters <= 3 characters

Example

RON
subtotal

A decimal amount as a string, e.g. “149.90”.

string | null
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
shipping

A decimal amount as a string, e.g. “149.90”.

string | null
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
tax

A decimal amount as a string, e.g. “149.90”.

string | null
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
discount

A decimal amount as a string, e.g. “149.90”.

string | null
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
total

A decimal amount as a string, e.g. “149.90”.

string | null
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
paymentMethod
string | null
<= 100 characters
billingAddress
object
label
string | null
<= 60 characters
line1
required
string
>= 1 characters <= 200 characters
line2
string | null
<= 200 characters
city
required
string
>= 1 characters <= 100 characters
region
string | null
<= 100 characters
postalCode
string | null
<= 20 characters
country
required

ISO 3166-1 alpha-2, e.g. RO.

string
>= 2 characters <= 2 characters
shippingAddress
object
label
string | null
<= 60 characters
line1
required
string
>= 1 characters <= 200 characters
line2
string | null
<= 200 characters
city
required
string
>= 1 characters <= 100 characters
region
string | null
<= 100 characters
postalCode
string | null
<= 20 characters
country
required

ISO 3166-1 alpha-2, e.g. RO.

string
>= 2 characters <= 2 characters
placedAt

ISO-8601 date-time, e.g. 2026-11-21T09:30:00Z.

string | null
<= 40 characters

Example

2026-11-21T09:30:00Z
items
Array<object> | null
<= 500 items
object
catalogItemId
string | null
>= 1 characters <= 64 characters
sku
string | null
<= 100 characters
name
required
string
>= 1 characters <= 300 characters
quantity
required
number
<= 1000000
unitPrice
required

A decimal amount as a string, e.g. “149.90”.

string
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
rowTotal

Defaults to quantity × unit price.

string | null
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
options
Array<object> | null
<= 50 items
object
label
required
string
<= 100 characters
value
required
string
<= 300 characters
custom

Custom field values keyed by field key; null clears one. See GET /products/{productId}/custom-fields.

object | null
items
Array<object> | null
<= 500 items
object
catalogItemId
string | null
>= 1 characters <= 64 characters
catalogItemExternalId

The catalog item, by its id in the same source.

string | null
>= 1 characters <= 128 characters
sku
string | null
<= 100 characters
name
required
string
>= 1 characters <= 300 characters
quantity
required
number
<= 1000000
unitPrice
required

A decimal amount as a string, e.g. “149.90”.

string
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
rowTotal

A decimal amount as a string, e.g. “149.90”.

string | null
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
options
Array<object> | null
<= 50 items
object
label
required
string
<= 100 characters
value
required
string
<= 300 characters
storeExternalId

The store, by its id in the same source.

string | null
>= 1 characters <= 128 characters
contactExternalId

The contact, by its id in the same source.

string | null
>= 1 characters <= 128 characters
clientExternalId

The client, by its id in the same source.

string | null
>= 1 characters <= 128 characters
subscriptionExternalId

The subscription it bills, by its id in the same source.

string | null
>= 1 characters <= 128 characters
contactEmail

For buyers without an id (guest checkout): the contact with this email, created when new.

string | null
<= 254 characters
contactName
string | null
<= 200 characters
shipments

Replaces the shipments this source sent for the order; others’ stay.

Array
<= 50 items
object
carrierCode
string | null
<= 40 characters
carrierName
string | null
<= 100 characters
trackingNumber
string | null
<= 100 characters
state
string | null
Allowed values: pending in_transit delivered returned canceled
deliveredAt

ISO-8601 date-time, e.g. 2026-11-21T09:30:00Z.

string | null
<= 40 characters

Example

2026-11-21T09:30:00Z
externalId
required

The record’s id in that system.

string
>= 1 characters <= 128 characters

Example

C-1042
history
Array<object> | null
<= 200 items
object
at
required

ISO-8601 date-time, e.g. 2026-11-21T09:30:00Z.

string
<= 40 characters

Example

2026-11-21T09:30:00Z
status
required
string
<= 200 characters
location
string | null
<= 200 characters
documents

Replaces the invoices and credit memos this source sent for the order; others’ stay.

Array
<= 50 items
object
kind
required
string
Allowed values: invoice credit_memo
number
string | null
<= 64 characters
amount
required

A decimal amount as a string, e.g. “149.90”.

string
<= 32 characters /^-?\d+(\.\d+)?$/

Example

149.90
reason
string | null
<= 500 characters
issuedAt

ISO-8601 date-time, e.g. 2026-11-21T09:30:00Z.

string | null
<= 40 characters

Example

2026-11-21T09:30:00Z
externalId
required

The record’s id in that system.

string
>= 1 characters <= 128 characters

Example

C-1042

Success

Media typeapplication/json
object
entity
required
string
id
required
string
>= 1 characters <= 64 characters
created
required

False when an existing record was updated (found by external id, or matched).

boolean
record
required
object
id
required
string
>= 1 characters <= 64 characters
storeId
required

Null only for a subscription’s invoice.

string | null
>= 1 characters <= 64 characters
storeName
required
string | null
number
required
string
contact
required
object
id
required
string
>= 1 characters <= 64 characters
name
required
string | null
email
required
string | null
client
required
object
id
required
string
>= 1 characters <= 64 characters
name
required
string | null
email
required
string | null
subscription
required
object
id
required
string
>= 1 characters <= 64 characters
planName
required
string
periodStart
required
string | null
periodEnd
required
string | null
status
required
string
Allowed values: pending processing on_hold shipped completed canceled refunded
statusRaw
required
string | null
paymentStatus
required
string | null
Allowed values: unpaid partially_paid paid refunded void
paidAt
required
string | null
dueAt
required
string | null
overdue
required
boolean
currency
required
string
subtotal
required
string | null
shipping
required
string | null
tax
required
string | null
discount
required
string | null
total
required
string
paymentMethod
required
string | null
billingAddress
required
object
label
required
string | null
line1
required
string
line2
required
string | null
city
required
string
region
required
string | null
postalCode
required
string | null
country
required
string
shippingAddress
required
object
label
required
string | null
line1
required
string
line2
required
string | null
city
required
string
region
required
string | null
postalCode
required
string | null
country
required
string
placedAt
required
string
items
required
Array<object>
object
catalogItemId
required
string | null
>= 1 characters <= 64 characters
sku
required
string | null
name
required
string
quantity
required
number
unitPrice
required
string
rowTotal
required
string
options
required
Array<object>
object
label
required
string
value
required
string
shipments
required
Array<object>
object
id
required
string
>= 1 characters <= 64 characters
carrierCode
required
string | null
carrierName
required
string | null
trackingNumber
required
string | null
state
required
string
Allowed values: pending in_transit delivered returned canceled
deliveredAt
required
string | null
key
additional properties
documents
required
Array<object>
object
id
required
string
>= 1 characters <= 64 characters
kind
required
string
Allowed values: invoice credit_memo
number
required
string | null
amount
required
string
reason
required
string | null
issuedAt
required
string
key
additional properties
custom
required
object
key
additional properties
source
required
string
externalId
required
string | null
createdAt
required
string
updatedAt
required
string
key
additional properties

Example

{
"record": {
"status": "pending",
"paymentStatus": "unpaid",
"shipments": [
{
"state": "pending"
}
],
"documents": [
{
"kind": "invoice"
}
]
}
}

Invalid request

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Missing, invalid, revoked or expired API key

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Missing scope, API turned off, published article without publish scope, or account suspended

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Not found, or outside the knowledge bases this key may use

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Slug or translation already exists

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Rejected by validation (e.g. unknown language or category)

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Rate limited; see Retry-After

Media typeapplication/json
object
error
required
object
code
required
string
message
required
string
field
string
details
Array<object>
object
code
required
string
message
required
string
field
string

Example

{
"error": {
"code": "SLUG_TAKEN"
}
}

Internal error