Skip to content

Record an order or a subscription's invoice

POST
/products/{productId}/orders
curl --request POST \
--url https://api.motenya.app/v1/products/example/orders \
--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", "sku": "example", "name": "example", "quantity": 1, "unitPrice": "149.90", "rowTotal": "149.90", "options": [ { "label": "example", "value": "example" } ] } ], "custom": "example" }'

Needs a store, unless subscriptionId makes it a subscription’s invoice. The number must be unique in its store, or among orders without one (ORDER_NUMBER_TAKEN otherwise).

Requires crm:write.

productId
required
string
>= 1 characters <= 64 characters
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
required
string
>= 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

Defaults to the sum of the items (a subscription invoice: the plan’s amount).

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

Success

Media typeapplication/json
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

{
"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