CustomerSubscription
A recurring agreement with one customer: what it covers, the interval it is billed at, when it started and when it is next invoiced.
- Summary view
- CustomerSubscriptionList, 20 fields. What a list returns by default.
- Detail view
- CustomerSubscription, 20 fields. The default for a single read and for every write.
Its lines live on the items sub-resource, and the renewal run turns a due subscription into a sales invoice. A subscription with no next invoice date is never invoiced automatically.
Used by
/customer-subscriptions/{customer_subscription}CustomerSubscription/customer-subscriptions/{customer_subscription}/actions/restoreCustomerSubscriptionFields
- Detail only
- Only in the detail view.
- Only with include
- Only when you ask for it with include.
- Server-assigned
- Set by plnnrly, never by a request.
The customer this subscription belongs to. Expanding it with ?include=customer additionally requires the customers::read permission and a token scope covering the customers prefix.
The subscription type this subscription is an instance of, which is also where its displayed name comes from. Expanding it with ?include=subscription_type additionally requires the subscription_types::read permission and a token scope covering the subscription_types prefix.
What this subscription covers, as free text. This is the field ?q= searches, and it is also what a generated invoice line falls back to.
Lifecycle status. Only an active subscription is picked up by the renewal run; the other three are inert.
pendingactivecancelledexpired
New values may be added.
How often the subscription is invoiced. one-time forces auto_renew to false, because a one-off has no next period to move on to.
yearlymonthlyone-time
New values may be added.
First day the subscription runs from, as a zone-free calendar date. Newest first is the default sort.
First day of the period to be invoiced next. Omit it on create and the server fills it with starts_at, so the first period is billable; the renewal run advances it by one interval each time it invoices. Null makes the subscription invisible to that run (it is skipped, silently), so a subscription that should never auto-invoice is expressed this way.
Day the subscription was cancelled, null while it has not been. It is a record of the cancellation date only: nothing derives status from it.
Whether the renewal run may invoice this subscription again. A one-time subscription is always false: it is forced on every save, so sending true together with billing_interval=one-time succeeds and comes back as false rather than failing.
Exact Online subscription this one maps to, by Exact's own external identifier, not by a local id. Written by the sync; null when the subscription has never been synced.
Day the subscription was last invoiced, null until it has been. Maintained by the renewal run.
Last-write timestamp; use for incremental sync. It also feeds the ETag revision, because a customer subscription has no version field.
Variants
CustomerSubscriptionList 20 fields
What a collection returns, and what ?view=summary returns on a single record.
The same fields as the detail object.
CustomerSubscriptionSummary 3 fields
The embedded form: what you get when another resource carries this one and you did not include it.
Leaves out: customer, subscription_type_id, subscription_type, description, status, billing_interval, next_invoice_date, cancelled_at, expires_at, auto_renew, exact_subscription_id, last_invoiced_at, created_at, updated_at, deleted_at, items_count, links
CustomerSubscriptionLinks 2 fields
The links object on this resource.
Keys: self, items
Something wrong or missing on this page? Tell us