Skip to content

Create or update a subscription by its id in your system

PUT
/products/{productId}/sync/subscriptions/{source}/{externalId}
curl --request PUT \
--url https://api.motenya.app/v1/products/example/sync/subscriptions/erp/C-1042 \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/json' \
--data '{ "contactId": "example", "clientId": "example", "catalogItemId": "example", "storeId": "example", "planName": "example", "status": "trialing", "amount": "149.90", "currency": "RON", "interval": "day", "intervalCount": 1, "seats": 1, "startedAt": "2026-11-21T09:30:00Z", "trialEndsAt": "2026-11-21T09:30:00Z", "currentPeriodEnd": "2026-11-21T09:30:00Z", "canceledAt": "2026-11-21T09:30:00Z", "endsAt": "2026-11-21T09:30:00Z", "custom": "example", "storeExternalId": "example", "contactExternalId": "example", "clientExternalId": "example", "catalogItemExternalId": "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).

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
contactId
string | null
>= 1 characters <= 64 characters
clientId
string | null
>= 1 characters <= 64 characters
catalogItemId
string | null
>= 1 characters <= 64 characters
storeId
string | null
>= 1 characters <= 64 characters
planName
string | null
>= 1 characters <= 200 characters
status
string | null
Allowed values: trialing active past_due paused canceled
amount

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
string | null
Allowed values: day week month year
intervalCount
integer | null
>= 1 <= 365
seats
integer | null
<= 1000000
startedAt

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

string | null
<= 40 characters

Example

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

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

string | null
<= 40 characters

Example

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

When the current paid period ends (the renewal).

string | null
<= 40 characters

Example

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

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

string | null
<= 40 characters

Example

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

When access ends; leave unset while it renews.

string | null
<= 40 characters

Example

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

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

object | null
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
catalogItemExternalId

The plan, 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
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
catalogItemId
required
string | null
>= 1 characters <= 64 characters
storeId
required
string | null
>= 1 characters <= 64 characters
planName
required
string
status
required
string
Allowed values: trialing active past_due paused canceled
amount
required
string
currency
required
string
interval
required
string
Allowed values: day week month year
intervalCount
required
integer
monthlyAmount
required

Amount per month, for MRR.

string
seats
required
integer | null
startedAt
required
string
trialEndsAt
required
string | null
currentPeriodEnd
required
string | null
canceledAt
required
string | null
endsAt
required
string | null
ended
required
boolean
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": "trialing",
"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