Subscriptions
A subscription connects a product licence to a location. Booking a listing subscription starts the publishing of the location data to the listing portals.
Book a subscription
| Step | Endpoint |
|---|---|
| 1. Find the company's contracts | GET Contract list with id = company ID |
| 2. Create a contract if none exists | POST Contract with parentType=Company |
| 3. Find licences that can be booked | GET Licence list with contextType=Company, products=Listing, statuses=ACTIVE |
| 4. Subscribe locations | POST Subscription with the licence ID in the path |
| 5. Check the result | GET Subscription list |
POST /subscription/{licenceId}?locationIds=1,2,3 requires startDate, which must be today or later. endDate is optional and must be after startDate. Set your own reference in externalId. The response lists the created subscription IDs. A multi-product licence creates one subscription per product.
{ "startDate": "2026-11-01", "externalId": "SUB-4711" }
Make sure the location is complete before you book. See Location profile data.
Check subscription status
GET Subscription list takes id and contextType (Licence or Location). Filter with products and statuses.
| Status | Meaning |
|---|---|
PROCESSING | Booking is being processed. Poll again later |
ACTIVE | Running |
EXPIRING | An end date is set |
FINISHED | Ended |
FAILED | Booking failed. Check the location data and the error message |
GET Subscription extended returns additional information from connected third-party systems. GET Listing list shows the state per portal.
Change a subscription
| Task | Endpoint |
|---|---|
| Update fields such as name, dates or product settings | PUT Subscription |
| Switch an add-on on or off | PUT Subscription add-on with addonId and state |
| Run a predefined action | POST Subscription action with actionId |
| Copy to other locations | POST Subscription copy with locationIds |
Cancel a subscription
DELETE Unsubscribe takes ids, a comma-separated list of subscription IDs. It returns the IDs that were cancelled.
Cancelling a subscription removes the listing content from the portals. Cancel before you delete a location or company.
Common problems
| Symptom | Cause and fix |
|---|---|
| Start date rejected | startDate is in the past. Use today or later |
| End date rejected | endDate must be in the future and after startDate |
Subscription stays FAILED | Read the Error object, fix the location data and subscribe again |
| No licence returned | The contract has no matching licence. Check the offer with GET Offer list and the contract |