Skip to content

Create or update a catalog item by its id in your system

PUT
/products/{productId}/sync/catalog-items/{source}/{externalId}
curl --request PUT \
--url https://api.motenya.app/v1/products/example/sync/catalog-items/erp/C-1042 \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "name": "example", "sku": "example", "kind": "product", "price": "149.90", "currency": "RON", "interval": "day", "intervalCount": 1, "storeId": "example", "custom": "example", "archived": true, "storeExternalId": "example" }'

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 item by SKU in the same store.

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
name
string | null
>= 1 characters <= 200 characters
sku
string | null
<= 100 characters
kind
string | null
Allowed values: product plan service
price

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

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

Example

149.90
currency

ISO 4217 code, e.g. RON or EUR.

string | null
>= 3 characters <= 3 characters

Example

RON
interval

Set for something billed on a schedule (a plan).

string | null
Allowed values: day week month year
intervalCount
integer | null
>= 1 <= 365
storeId

Sold only in this store; null for every store.

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

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

object | null
archived
boolean | null
storeExternalId

The store, by its id in the same source.

string | null
>= 1 characters <= 128 characters

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
name
required
string
sku
required
string | null
kind
required
string
Allowed values: product plan service
price
required
string | null
currency
required
string | null
interval
required
string | null
Allowed values: day week month year
intervalCount
required
integer
storeId
required
string | null
>= 1 characters <= 64 characters
custom
required
object
key
additional properties
source
required
string
externalId
required
string | null
archived
required
boolean
createdAt
required
string
updatedAt
required
string
key
additional properties

Example

{
"record": {
"kind": "product",
"interval": "day"
}
}

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