Sales | Service Instances

List provided service instances

get

You can only access service instances that you provide. Note: the "supplier" field will always be null since the result is only about the instances you provide.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Query parameters

servicesinteger · int32[]Optional

Filter by one or multiple specific services of your portfolio

customersinteger · int32[]Optional

Filter by one or multiple specific customers

locationsinteger · int32[]Optional

Filter by one or multiple specific locations

employeesinteger · int32[]Optional

Filter by one or multiple specific employees

groupsinteger · int32[]Optional

Filter by one or multiple specific groups

statusesstring[]Optional

Filter by one or multiple specific statuses

activebooleanOptional

Filter the instances which are active or not active. When null, all instances will be returned. Default: null

subscriptionPeriodRenewalsinteger · int32[]Optional

Filter by one or multiple specific values for the period renewal, e.g. to filter all without a renewal use 0

modifiedSincestring · date-timeOptional

Filter the instances modified after the specified date. A modification is identified when: the assignment changed, the instance got activated, the instance got cancelled

expiresAfterstring · date-timeOptional

Filter the instances which expire after this date

expiresBeforestring · date-timeOptional

Filter the instances which expire before this date

searchstringOptional

Filter for id, service name, inventory number, employee first and last name, group, location name or metadata values

sortBystring · enumOptional

Sort the instances by a given criterion

Possible values:

sortOrderstring · enumOptional

Order in which the result of a list request is sorted.

Possible values:

offsetinteger · int32Optional

Specifies the index of the first instances to return

Default: 0

limitinteger · int32Optional

Specifies the maximum number of instances to return

Default: 100

Responses

200

OK: A list of service instances.

application/json

totalinteger · int32Required

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key.

application/json

403

Forbidden: Resource access denied or resource does not exist anymore.

application/json

get/v1/sales/service-instances

GET /v1/sales/service-instances HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "previous": {
    "href": "text",
    "method": "text"
  },
  "next": {
    "href": "text",
    "method": "text"
  },
  "items": [
    {
      "supplier": {
        "id": 4,
        "name": "foo Inc.",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "service": {
        "id": 4,
        "name": "Basic Plan",
        "category": "text",
        "ean": "0194253408253",
        "externalId": "E54363",
        "supplierName": "text",
        "previewImageLink": "text",
        "type": "service",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "customer": {
        "id": 4,
        "name": "foo Inc.",
        "customerNumber": "C00001",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "location": {
        "id": 1,
        "name": "HQ New York",
        "type": "location",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "group": {
        "id": 42,
        "name": "Project 1337",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "employee": {
        "id": 1,
        "firstName": "Pierce",
        "lastName": "Bell",
        "fullName": "text",
        "email": "p.bell@foo.io",
        "username": "j.doe@foo.inc",
        "costCenter": "4645-2343",
        "costCenterId": 1,
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "activationDate": "2026-07-15T13:40:25.925Z",
      "lastModifiedDate": "2026-07-15T13:40:25.925Z",
      "expirationDate": "2026-07-15T13:40:25.925Z",
      "processStatus": "ordered",
      "active": true,
      "oneTimeCosts": 92.99,
      "recurringCosts": 109.9,
      "currencyCode": "EUR",
      "subscriptionPeriod": 12,
      "subscriptionPeriodRenewal": 1,
      "note": "This is just a <b>custom note</b>.",
      "metadata": [
        {
          "key": "Serial number",
          "value": "SN45346X2345",
          "scope": "public"
        }
      ],
      "id": 42,
      "inventoryNumber": "EQ642",
      "costCenter": "4645-2343",
      "self": {
        "href": "text",
        "method": "text"
      }
    }
  ],
  "total": 1,
  "self": {
    "href": "text",
    "method": "text"
  }
}

Create a new service instance

post

Every service instance is based on a service and its offer. So an offer id needs to be provided. Please use sales service and/or sales service offer POST endpoints to create the required information, if missing.

Therefore please provide assignment information etc. regarding the configuration of the service in the portfolio.

It is only possible to create active service instance therefore an activation date needs to be provided.

It is only possible to create service instances for your managed customers or your own customer entity. You can not create them e.g. for partner customers.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Body

offerIdinteger · int32 · min: 1 · max: 2147483647Required

The id of the corresponding sales service offer. The offer is used as the base for the instances price and period.

To overwrite prices and periods of the offer for the service instance to be created, set values OneTimeCosts, RecurringCosts, SubscriptionPeriod and SubscriptionPeriodRenewal

Offer and related service must be available for the customer, i.e. either no customer limitation exists or it contains the customer for whom the instance is to be created.

Example: 121

customerIdinteger · int32 · nullableOptional

The id of the customer to assign the service instance to. If no id is provided, the instance will be created in the provided tenant context (see Tenant header).

Example: 42

groupIdinteger · int32 · nullableOptional

The id of the group to assign the service instance to.

Example: 13

notestring · max: 10000 · nullableOptional

A note on the service instance. Supports html formatted text including inline css styles.

Example: This is just a custom note.

oneTimeCostsnumber · double · max: 1.7976931348623157e+308 · nullableOptional

One-time purchase costs of the instance in its life cycle to date. When set, overwrites the value of the provided offer for this service instance.

Example: 92.99

recurringCostsnumber · double · max: 1.7976931348623157e+308 · nullableOptional

The current recurring costs for the service instance. When set, overwrites the value of the provided offer for this service instance.

Example: 109.9

subscriptionPeriodinteger · int32 · max: 2147483647 · nullableOptional

The minimum subscription period (in months) for the services instance. When set, overwrites the value of the provided offer for this service instance.

Example: 12

subscriptionPeriodRenewalinteger · int32 · max: 2147483647 · nullableOptional

Number of months a subscription is renewed after its expiration time if it has not been terminated. When set, overwrites the value of the provided offer for this service instance.

Example: 1

activationDatestring · date-time · nullableOptional

The date the service instance was activated. If no date is provided UtcNow will be used. Currently only active instances can be created which always need an activation date. The activation date can only be set to the past.

Example: 2021-06-08T11:34:30

expirationDatestring · date-time · nullableOptional

The date when the service instance should expire. If not provided this gets calculated based on the ActivationDate added by the SubscriptionPeriod and will extend based on the SubscriptionPeriodRenewal.

The expiration date must not be before the activation date.

locationIdinteger · int32 · nullableOptional

The id of the location to assign the service instance to. Needs to be a valid location of the customer. Null will remove the location assignment.

Example: 13

employeeIdinteger · int32 · nullableOptional

The id of the employee to assign the service instance to. Needs to be a valid employee of the customer. Null will remove the employee assignment.

Example: 12

inventoryNumberstring · max: 50 · nullableOptional

The inventory number of the service instance.

Example: EQ642

Responses

201

Created: The created service instance.

application/json

activationDatestring · date-time · nullableOptional

The date the service instance was activated.

lastModifiedDatestring · date-time · nullableOptional

The date the service instance was last modified.

expirationDatestring · date-time · nullableOptional

The date when the service instance should expire.

processStatusstring · nullableOptional

The processing status of the service instance.

Example: ordered

activebooleanOptional

True if the service instance is active, otherwise false.

Example: true

oneTimeCostsnumber · doubleOptional

One-time purchase costs of the instance in its life cycle to date.

Example: 92.99

recurringCostsnumber · doubleOptional

The current recurring costs for the service instance. Only calculated for active instances.

Example: 109.9

currencyCodestring · nullableOptional

Currency in ISO 4217

Example: EUR

subscriptionPeriodinteger · int32 · nullableOptional

The minimum subscription period (in months) for the services instance.

Example: 12

subscriptionPeriodRenewalinteger · int32 · nullableOptional

Number of months a subscription is renewed after its expiration time if it has not been terminated.

Example: 1

notestring · nullableOptional

A note on the service instance. Supports html formatted text including inline css styles.

Example: This is just a custom note.

idinteger · int32Required

The id to identify the service instance in the system.

Example: 42

inventoryNumberstring · max: 50 · nullableOptional

The inventory number of the service instance.

Example: EQ642

costCenterstring · nullableOptional

The name of the cost center to which the service instance belongs.

Example: 4645-2343

400

Bad request: Body validation failed, creation of instance for the provided service is not possible or assignment information (employee, location etc.) is invalid regarding the context of the service. See response message for details.

application/json

401

Unauthorized: Invalid api key.

application/json

403

Forbidden: Resource access denied or resource does not exist.

application/json

404

NotFound: One of the given references (e.g. offer) can not be found.

409

Conflict: Given offer is not available for the given customer, there are service dependencies which not to be resolved first or another conflict regarding the portfolio configuration occurs. See response message for details.

post/v1/sales/service-instances

POST /v1/sales/service-instances HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 404

{
  "offerId": 121,
  "customerId": 42,
  "groupId": 13,
  "note": "This is just a <b>custom note</b>.",
  "oneTimeCosts": 92.99,
  "recurringCosts": 109.9,
  "subscriptionPeriod": 12,
  "subscriptionPeriodRenewal": 1,
  "activationDate": "2021-06-08T11:34:30",
  "expirationDate": "2026-07-15T13:40:25.925Z",
  "metadata": [
    {
      "key": "Serial number",
      "value": "SN45346X2345",
      "scope": "public"
    }
  ],
  "locationId": 13,
  "employeeId": 12,
  "inventoryNumber": "EQ642"
}

{
  "supplier": {
    "id": 4,
    "name": "foo Inc.",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "service": {
    "id": 4,
    "name": "Basic Plan",
    "category": "text",
    "ean": "0194253408253",
    "externalId": "E54363",
    "supplierName": "text",
    "previewImageLink": "text",
    "type": "service",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "customer": {
    "id": 4,
    "name": "foo Inc.",
    "customerNumber": "C00001",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "location": {
    "id": 1,
    "name": "HQ New York",
    "type": "location",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "group": {
    "id": 42,
    "name": "Project 1337",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "employee": {
    "id": 1,
    "firstName": "Pierce",
    "lastName": "Bell",
    "fullName": "text",
    "email": "p.bell@foo.io",
    "username": "j.doe@foo.inc",
    "costCenter": "4645-2343",
    "costCenterId": 1,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "activationDate": "2026-07-15T13:40:25.925Z",
  "lastModifiedDate": "2026-07-15T13:40:25.925Z",
  "expirationDate": "2026-07-15T13:40:25.925Z",
  "processStatus": "ordered",
  "active": true,
  "oneTimeCosts": 92.99,
  "recurringCosts": 109.9,
  "currencyCode": "EUR",
  "subscriptionPeriod": 12,
  "subscriptionPeriodRenewal": 1,
  "note": "This is just a <b>custom note</b>.",
  "metadata": [
    {
      "key": "Serial number",
      "value": "SN45346X2345",
      "scope": "public"
    }
  ],
  "id": 42,
  "inventoryNumber": "EQ642",
  "costCenter": "4645-2343",
  "self": {
    "href": "text",
    "method": "text"
  }
}

Retrieve a single service instance by its id

get

You can only access service instances that you provide.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

Responses

200

OK: The requested service instance.

application/json

activationDatestring · date-time · nullableOptional

The date the service instance was activated.

lastModifiedDatestring · date-time · nullableOptional

The date the service instance was last modified.

expirationDatestring · date-time · nullableOptional

The date when the service instance should expire.

processStatusstring · nullableOptional

The processing status of the service instance.

Example: ordered

activebooleanOptional

True if the service instance is active, otherwise false.

Example: true

oneTimeCostsnumber · doubleOptional

One-time purchase costs of the instance in its life cycle to date.

Example: 92.99

recurringCostsnumber · doubleOptional

The current recurring costs for the service instance. Only calculated for active instances.

Example: 109.9

currencyCodestring · nullableOptional

Currency in ISO 4217

Example: EUR

subscriptionPeriodinteger · int32 · nullableOptional

The minimum subscription period (in months) for the services instance.

Example: 12

subscriptionPeriodRenewalinteger · int32 · nullableOptional

Number of months a subscription is renewed after its expiration time if it has not been terminated.

Example: 1

notestring · nullableOptional

A note on the service instance. Supports html formatted text including inline css styles.

Example: This is just a custom note.

idinteger · int32Required

The id to identify the service instance in the system.

Example: 42

inventoryNumberstring · max: 50 · nullableOptional

The inventory number of the service instance.

Example: EQ642

costCenterstring · nullableOptional

The name of the cost center to which the service instance belongs.

Example: 4645-2343

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

get/v1/sales/service-instances/{instanceId}

GET /v1/sales/service-instances/{instanceId} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "supplier": {
    "id": 4,
    "name": "foo Inc.",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "service": {
    "id": 4,
    "name": "Basic Plan",
    "category": "text",
    "ean": "0194253408253",
    "externalId": "E54363",
    "supplierName": "text",
    "previewImageLink": "text",
    "type": "service",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "customer": {
    "id": 4,
    "name": "foo Inc.",
    "customerNumber": "C00001",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "location": {
    "id": 1,
    "name": "HQ New York",
    "type": "location",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "group": {
    "id": 42,
    "name": "Project 1337",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "employee": {
    "id": 1,
    "firstName": "Pierce",
    "lastName": "Bell",
    "fullName": "text",
    "email": "p.bell@foo.io",
    "username": "j.doe@foo.inc",
    "costCenter": "4645-2343",
    "costCenterId": 1,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "activationDate": "2026-07-15T13:40:25.925Z",
  "lastModifiedDate": "2026-07-15T13:40:25.925Z",
  "expirationDate": "2026-07-15T13:40:25.925Z",
  "processStatus": "ordered",
  "active": true,
  "oneTimeCosts": 92.99,
  "recurringCosts": 109.9,
  "currencyCode": "EUR",
  "subscriptionPeriod": 12,
  "subscriptionPeriodRenewal": 1,
  "note": "This is just a <b>custom note</b>.",
  "metadata": [
    {
      "key": "Serial number",
      "value": "SN45346X2345",
      "scope": "public"
    }
  ],
  "id": 42,
  "inventoryNumber": "EQ642",
  "costCenter": "4645-2343",
  "self": {
    "href": "text",
    "method": "text"
  }
}

Update an existing service instance

put

To update location and/or employee assignments please consider: this endpoint currently not supports to move service instances from or to a warehouse. Change assignments between locations of the same type is supported though.

When assigning a remote work location the employee of this remote work location also needs to be assigned.

Changing or removing the location/employee assignment might be restricted by the context settings of the service in the portfolio. When running into issues, please ensure that the service of the instance has the required context enabled.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

Body

locationIdinteger · int32 · nullableOptional

The id of the location to assign the service instance to. Needs to be a valid location of the customer. Null will remove the location assignment.

Example: 13

employeeIdinteger · int32 · nullableOptional

The id of the employee to assign the service instance to. Needs to be a valid employee of the customer. Null will remove the employee assignment.

Example: 12

inventoryNumberstring · max: 50 · nullableOptional

The inventory number of the service instance.

Example: EQ642

Responses

200

OK: Returns the updated service instance.

application/json

activationDatestring · date-time · nullableOptional

The date the service instance was activated.

lastModifiedDatestring · date-time · nullableOptional

The date the service instance was last modified.

expirationDatestring · date-time · nullableOptional

The date when the service instance should expire.

processStatusstring · nullableOptional

The processing status of the service instance.

Example: ordered

activebooleanOptional

True if the service instance is active, otherwise false.

Example: true

oneTimeCostsnumber · doubleOptional

One-time purchase costs of the instance in its life cycle to date.

Example: 92.99

recurringCostsnumber · doubleOptional

The current recurring costs for the service instance. Only calculated for active instances.

Example: 109.9

currencyCodestring · nullableOptional

Currency in ISO 4217

Example: EUR

subscriptionPeriodinteger · int32 · nullableOptional

The minimum subscription period (in months) for the services instance.

Example: 12

subscriptionPeriodRenewalinteger · int32 · nullableOptional

Number of months a subscription is renewed after its expiration time if it has not been terminated.

Example: 1

notestring · nullableOptional

A note on the service instance. Supports html formatted text including inline css styles.

Example: This is just a custom note.

idinteger · int32Required

The id to identify the service instance in the system.

Example: 42

inventoryNumberstring · max: 50 · nullableOptional

The inventory number of the service instance.

Example: EQ642

costCenterstring · nullableOptional

The name of the cost center to which the service instance belongs.

Example: 4645-2343

400

Bad request: Body validation failed. See response message for details.

application/json

401

Unauthorized: Invalid api key.

application/json

403

Forbidden: Resource access denied or resource does not exist anymore.

application/json

404

NotFound: Requested resource could not be found.

application/json

put/v1/sales/service-instances/{instanceId}

PUT /v1/sales/service-instances/{instanceId} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 59

{
  "locationId": 13,
  "employeeId": 12,
  "inventoryNumber": "EQ642"
}

{
  "supplier": {
    "id": 4,
    "name": "foo Inc.",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "service": {
    "id": 4,
    "name": "Basic Plan",
    "category": "text",
    "ean": "0194253408253",
    "externalId": "E54363",
    "supplierName": "text",
    "previewImageLink": "text",
    "type": "service",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "customer": {
    "id": 4,
    "name": "foo Inc.",
    "customerNumber": "C00001",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "location": {
    "id": 1,
    "name": "HQ New York",
    "type": "location",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "group": {
    "id": 42,
    "name": "Project 1337",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "employee": {
    "id": 1,
    "firstName": "Pierce",
    "lastName": "Bell",
    "fullName": "text",
    "email": "p.bell@foo.io",
    "username": "j.doe@foo.inc",
    "costCenter": "4645-2343",
    "costCenterId": 1,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "activationDate": "2026-07-15T13:40:25.925Z",
  "lastModifiedDate": "2026-07-15T13:40:25.925Z",
  "expirationDate": "2026-07-15T13:40:25.925Z",
  "processStatus": "ordered",
  "active": true,
  "oneTimeCosts": 92.99,
  "recurringCosts": 109.9,
  "currencyCode": "EUR",
  "subscriptionPeriod": 12,
  "subscriptionPeriodRenewal": 1,
  "note": "This is just a <b>custom note</b>.",
  "metadata": [
    {
      "key": "Serial number",
      "value": "SN45346X2345",
      "scope": "public"
    }
  ],
  "id": 42,
  "inventoryNumber": "EQ642",
  "costCenter": "4645-2343",
  "self": {
    "href": "text",
    "method": "text"
  }
}

Remove a service instance from the customers inventory

delete

Sets the service instance to status 'removed' including all processes to remove the instance (e.g. stop and refund billing). The instance history still remains. Behavior is the same as when the customer cancels the service and termination gets processed.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance to be removed.

Query parameters

processingDatestring · date-timeOptional

The date on which the deletion is processed. Value must not be in the future

Responses

204

NoContent: Remove successful.

No content

400

Bad request: Body validation failed. See response message for details.

application/json

401

Unauthorized: Invalid api key.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

409

Conflict: Can not remove, because there are unprocessed changes or transition is invalid because of current status or open dependencies. See response message for details.

delete/v1/sales/service-instances/{instanceId}

DELETE /v1/sales/service-instances/{instanceId} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

No content

Create a cancellation for a service instance

post

Creates a cancellation order item for the given service instance. The cancellation will be processed either manually via the fulfillment orders endpoint or automatically on the specified scheduledProcessingDate.

You can only cancel service instances that you provide.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance to cancel.

Body

Request body for creating a service instance cancellation.

scheduledProcessingDatestring · date · nullableOptional

The date on which the cancellation order item should be automatically processed. When omitted the order item will not be processed automatically and must be processed manually.

Responses

201

Created: The created cancellation fulfillment order.

application/json

transactionTypestring · enumRequired

The action triggered by a fulfillment order.

Possible values:

statusstring · enumRequired

Status of the fulfillment process.

Possible values:

fulfillmentTypestring · enumOptional

Types of fulfillment to complete a customer order.

Possible values:

isPreorderbooleanOptional

Indicates whether this order is a preorder. Preorders should only be prepared until ready for delivery and then wait to be requested by the customer before shipment.

partnerNotestring · nullableOptional

A note shared with the intermediary partner. (Only for orders placed by partner customers)

Example: Contract number: 154587858

preferredProvisionDatestring · date-time · nullableOptional

The preferred provision date.

totalRecurringPricenumber · doubleOptional

Sum of the recurring prices of the service offer and the ordered options in this item.

totalPurchasePricenumber · doubleOptional

Sum of the purchase prices of the service offer and the ordered options in this item.

idinteger · int64Required

The identifier of the order.

Example: 13

externalIdstring · nullableOptional

The identifier of the order in an external app.

Example: 5214e3bed1454eaf

400

Bad request: Body validation failed. See response message for details.

application/json

401

Unauthorized: Invalid api key.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

409

Conflict: Service instance is not in a cancellable state.

application/json

post/v1/sales/service-instances/{instanceId}/cancel

POST /v1/sales/service-instances/{instanceId}/cancel HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 40

{
  "scheduledProcessingDate": "2026-07-15"
}

{
  "transactionType": "order",
  "status": "new",
  "fulfillmentType": "in-house",
  "isPreorder": true,
  "partnerNote": "Contract number: 154587858",
  "offer": {
    "id": 99,
    "type": "rental",
    "purchasePrice": 99.99,
    "recurringPrice": 19.99,
    "currency": "EUR",
    "subscriptionPeriod": 12,
    "name": "Summer Deal",
    "externalId": "W5A345",
    "isDefault": true,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "service": {
    "id": 4,
    "name": "Basic Plan",
    "category": "text",
    "ean": "0194253408253",
    "externalId": "E54363",
    "supplierName": "text",
    "previewImageLink": "text",
    "type": "service",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "options": [
    {
      "offer": {
        "id": 99,
        "purchasePrice": 99.99,
        "recurringPrice": 19.99,
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "option": {
        "id": 42,
        "name": "Color",
        "self": {
          "href": "text",
          "method": "text"
        }
      },
      "version": {
        "id": 42,
        "name": "Red",
        "self": {
          "href": "text",
          "method": "text"
        }
      }
    }
  ],
  "order": {
    "id": 2324576,
    "customerOrderNumber": "RQ12345",
    "orderNumber": "4321",
    "created": "2021-06-08T11:34:30",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "customer": {
    "id": 4,
    "name": "foo Inc.",
    "customerNumber": "C00001",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "orderedBy": {
    "id": 1,
    "firstName": "Pierce",
    "lastName": "Bell",
    "email": "p.bell@foo.io",
    "phoneBusiness": "+49 555 6273",
    "phoneMobile": "+49 555 4523",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "deliveryAddress": {
    "line1": "equipme GmbH",
    "street": "W 55th St",
    "number": 240,
    "addition": "3rd floor",
    "city": "New York",
    "postalCode": 10019,
    "countryCode": "US",
    "regionCode": "NY",
    "regionName": "New York",
    "dependentLocality": "Chilmington Green",
    "phoneNumber": "+1 212-555-1234",
    "id": 83,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "billingAddress": {
    "line1": "equipme GmbH",
    "street": "W 55th St",
    "number": 240,
    "addition": "3rd floor",
    "city": "New York",
    "postalCode": 10019,
    "countryCode": "US",
    "regionCode": "NY",
    "regionName": "New York",
    "dependentLocality": "Chilmington Green",
    "phoneNumber": "+1 212-555-1234",
    "id": 83,
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "preferredProvisionDate": "2026-07-15T13:40:25.925Z",
  "serviceInstance": {
    "id": 42,
    "inventoryNumber": "EQ642",
    "costCenter": "4645-2343",
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "targetServiceInstance": {
    "id": 42,
    "service": {
      "id": 4,
      "name": "Basic Plan",
      "category": "text",
      "ean": "0194253408253",
      "externalId": "E54363",
      "supplierName": "text",
      "previewImageLink": "text",
      "type": "service",
      "self": {
        "href": "text",
        "method": "text"
      }
    },
    "metadata": [
      {
        "key": "Serial number",
        "value": "SN45346X2345",
        "scope": "public"
      }
    ],
    "self": {
      "href": "text",
      "method": "text"
    }
  },
  "assignments": {
    "location": {
      "id": 1,
      "name": "HQ New York",
      "type": "location",
      "self": {
        "href": "text",
        "method": "text"
      }
    },
    "employee": {
      "id": 1,
      "firstName": "Pierce",
      "lastName": "Bell",
      "email": "p.bell@foo.io",
      "phoneBusiness": "+49 555 6273",
      "phoneMobile": "+49 555 4523",
      "self": {
        "href": "text",
        "method": "text"
      }
    }
  },
  "bomItems": [
    {
      "quantity": 1,
      "product": {
        "id": 1,
        "name": "Basic Plan",
        "partNumber": "EQ-0001",
        "externalId": "3704e3bed2654eaf8222800068f62b56",
        "self": {
          "href": "text",
          "method": "text"
        }
      }
    }
  ],
  "totalRecurringPrice": 1,
  "totalPurchasePrice": 1,
  "id": 13,
  "externalId": "5214e3bed1454eaf",
  "self": {
    "href": "text",
    "method": "text"
  }
}

List metadata of a service instance

get

Retrieves the metadata of a service instance as a list of key/value pairs.

You can only access service instances that you provide.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

Responses

200

OK: Service instance meta data.

application/json

keystring · max: 150Required

Key of the metadata entry.

Example: Serial number

valuestring · max: 500Required

The value of the metadata entry.

Example: SN45346X2345

scopestring · enumOptional

Defines for whom a metadata entry is visible. public: visible to all who have access to the service instance | internal: visible only to the author tenant

Possible values:

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

get/v1/sales/service-instances/{instanceId}/metadata

GET /v1/sales/service-instances/{instanceId}/metadata HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

[
  {
    "key": "Serial number",
    "value": "SN45346X2345",
    "scope": "public"
  }
]

Create or update the metadata of a service instance

put

The provided request body has to be a list of key/value pairs (see schema below).

A metadata key has to be unique within a service instance. If you provide the same key twice, the value of the first entry will just be overwritten.

You can only update metadata which was created by your provider entity.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

Bodyobject · MetadataEntry[]

keystring · max: 150Required

Key of the metadata entry.

Example: Serial number

valuestring · max: 500Required

The value of the metadata entry.

Example: SN45346X2345

scopestring · enumOptional

Defines for whom a metadata entry is visible. public: visible to all who have access to the service instance | internal: visible only to the author tenant

Possible values:

Responses

204

NoContent: Request has succeeded.

No content

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

put/v1/sales/service-instances/{instanceId}/metadata

PUT /v1/sales/service-instances/{instanceId}/metadata HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 65

[
  {
    "key": "Serial number",
    "value": "SN45346X2345",
    "scope": "public"
  }
]

No content

Delete all metadata of a service instance

delete

You can only delete metadata which was created by your provider entity.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

Responses

204

NoContent: Request has succeeded.

No content

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

delete/v1/sales/service-instances/{instanceId}/metadata

DELETE /v1/sales/service-instances/{instanceId}/metadata HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

No content

Retrieve a metadata entry of a service instance by its specified key

get

Retrieves a single metadata entry of a service instance as a key/value pair.

You can only access metadata of service instances that you provide.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

keystringRequired

The key of the metadata value to retrieve.

Responses

200

OK: Service instance meta data value.

application/json

keystring · max: 150Required

Key of the metadata entry.

Example: Serial number

valuestring · max: 500Required

The value of the metadata entry.

Example: SN45346X2345

scopestring · enumOptional

Defines for whom a metadata entry is visible. public: visible to all who have access to the service instance | internal: visible only to the author tenant

Possible values:

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

get/v1/sales/service-instances/{instanceId}/metadata/{key}

GET /v1/sales/service-instances/{instanceId}/metadata/{key} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

{
  "key": "Serial number",
  "value": "SN45346X2345",
  "scope": "public"
}

Create or update a single metadata entry of a service instance

put

The provided request body has to be a metadata value(see schema below).

A metadata key is unique within a service instance. If you want to add the same information but with a different key, remove the existing and add the data as a new entry.

You can only update metadata which was created by your provider entity.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

keystring · max: 150Required

The key of the metadata value to create or update.

Body

valuestring · max: 500Required

The value of the metadata entry.

Example: SN45346X2345

scopestring · enumOptional

Defines for whom a metadata entry is visible. public: visible to all who have access to the service instance | internal: visible only to the author tenant

Possible values:

Responses

204

NoContent: Request has succeeded.

No content

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

put/v1/sales/service-instances/{instanceId}/metadata/{key}

PUT /v1/sales/service-instances/{instanceId}/metadata/{key} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 41

{
  "value": "SN45346X2345",
  "scope": "public"
}

No content

Delete a single metadata entry of a service instance.

delete

You can only delete metadata which was created by your provider entity.

Authorizations

X-API-KEYstringRequired

Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.

Path parameters

instanceIdinteger · int32Required

The identifier of the service instance.

keystringRequired

The key of the metadata value to delete.

Responses

204

NoContent: Request has succeeded.

No content

400

Bad request: See response message for details.

application/json

401

Unauthorized: Invalid api key or expired access token.

application/json

403

Forbidden: Resource access denied.

application/json

404

NotFound: Requested resource could not be found.

application/json

delete/v1/sales/service-instances/{instanceId}/metadata/{key}

DELETE /v1/sales/service-instances/{instanceId}/metadata/{key} HTTP/1.1
X-API-KEY: YOUR_API_KEY
Accept: */*

No content

Last updated 1 hour ago

Was this helpful?