> For the complete documentation index, see [llms.txt](https://hub.equipme.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://hub.equipme.io/development/api-reference-pro/sales-or-service-instances.md). # Sales | Service Instances ## List provided service instances > 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. ```json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ServiceInstanceSortParameter":{"enum":["product","supplier","customer","oneTimeCosts","recurringCosts","activationDate","lastModified","expirationDate","inventoryNumber"],"type":"string"},"SortOrder":{"enum":["asc","desc"],"type":"string","description":"Order in which the result of a list request is sorted."},"ServiceInstanceList":{"required":["items","self","total"],"type":"object","properties":{"previous":{"$ref":"#/components/schemas/ResourceLink"},"next":{"$ref":"#/components/schemas/ResourceLink"},"items":{"type":"array","items":{"$ref":"#/components/schemas/ServiceInstance"}},"total":{"type":"integer","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ServiceInstance":{"required":["id","self"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"location":{"$ref":"#/components/schemas/LocationReference"},"group":{"$ref":"#/components/schemas/GroupReference"},"employee":{"$ref":"#/components/schemas/EmployeeReference"},"activationDate":{"type":"string","description":"The date the service instance was activated.","format":"date-time","nullable":true},"lastModifiedDate":{"type":"string","description":"The date the service instance was last modified.","format":"date-time","nullable":true},"expirationDate":{"type":"string","description":"The date when the service instance should expire.","format":"date-time","nullable":true},"processStatus":{"type":"string","description":"The processing status of the service instance.","nullable":true},"active":{"type":"boolean","description":"True if the service instance is active, otherwise false."},"oneTimeCosts":{"type":"number","description":"One-time purchase costs of the instance in its life cycle to date.","format":"double"},"recurringCosts":{"type":"number","description":"The current recurring costs for the service instance. Only calculated for active instances.","format":"double"},"currencyCode":{"type":"string","description":"Currency in ISO 4217","nullable":true},"subscriptionPeriod":{"type":"integer","description":"The minimum subscription period (in months) for the services instance.","format":"int32","nullable":true},"subscriptionPeriodRenewal":{"type":"integer","description":"Number of months a subscription is renewed after its expiration time if it has not been terminated.","format":"int32","nullable":true},"note":{"type":"string","description":"A note on the service instance. Supports html formatted text including inline css styles.","nullable":true},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"},"description":"Service instance metadata. Metadata can be used to store dynamic key value paired information on an instance.","nullable":true},"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true},"costCenter":{"type":"string","description":"The name of the cost center to which the service instance belongs.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the service.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the service."},"category":{"type":"string","description":"The category of the service. Comes from the marketplace ProductDisplayGroup","nullable":true},"ean":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service. (Max. 50 characters)","nullable":true},"externalId":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service.","nullable":true},"supplierName":{"type":"string","description":"The supplier for this service product","nullable":true},"previewImageLink":{"type":"string","description":"Link to a small preview image for the product","nullable":true},"type":{"$ref":"#/components/schemas/ServiceProductType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductType":{"enum":["service","addon","foundation_service"],"type":"string","description":"Services can take on different types that define their meaning and process flows within the system."},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"GroupReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances":{"get":{"tags":["Sales | Service Instances"],"summary":"List provided service instances","description":"You can only access service instances that you provide.\nNote: the \"supplier\" field will always be null since the result is only about the instances you provide.","parameters":[{"name":"services","in":"query","description":"Filter by one or multiple specific services of your portfolio","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"customers","in":"query","description":"Filter by one or multiple specific customers","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"locations","in":"query","description":"Filter by one or multiple specific locations","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"employees","in":"query","description":"Filter by one or multiple specific employees","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"groups","in":"query","description":"Filter by one or multiple specific groups","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"statuses","in":"query","description":"Filter by one or multiple specific statuses","schema":{"type":"array","items":{"type":"string"}}},{"name":"active","in":"query","description":"Filter the instances which are active or not active. When null, all instances will be returned. Default: null","schema":{"type":"boolean"}},{"name":"subscriptionPeriodRenewals","in":"query","description":"Filter by one or multiple specific values for the period renewal, e.g. to filter all without a renewal use 0","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"modifiedSince","in":"query","description":"Filter the instances modified after the specified date. A modification is identified when: the assignment changed, the instance got activated, the instance got cancelled","schema":{"type":"string","format":"date-time"}},{"name":"expiresAfter","in":"query","description":"Filter the instances which expire after this date","schema":{"type":"string","format":"date-time"}},{"name":"expiresBefore","in":"query","description":"Filter the instances which expire before this date","schema":{"type":"string","format":"date-time"}},{"name":"search","in":"query","description":"Filter for id, service name, inventory number, employee first and last name, group, location name or metadata values","schema":{"type":"string"}},{"name":"sortBy","in":"query","description":"Sort the instances by a given criterion","schema":{"$ref":"#/components/schemas/ServiceInstanceSortParameter"}},{"name":"sortOrder","in":"query","description":"Sort the instances in a given order (asc|desc)","schema":{"$ref":"#/components/schemas/SortOrder"}},{"name":"offset","in":"query","description":"Specifies the index of the first instances to return","schema":{"type":"integer","format":"int32","default":0}},{"name":"limit","in":"query","description":"Specifies the maximum number of instances to return","schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"description":"OK: A list of service instances.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInstanceList"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Create a new service instance > 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. ```json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ServiceInstanceCreate":{"required":["offerId"],"type":"object","properties":{"offerId":{"maximum":2147483647,"minimum":1,"type":"integer","description":"The id of the corresponding sales service offer. The offer is used as the base for the instances price and period.\n\nTo overwrite prices and periods of the offer for the service instance to be created, set values OneTimeCosts, RecurringCosts, SubscriptionPeriod and SubscriptionPeriodRenewal\n\nOffer 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.","format":"int32"},"customerId":{"type":"integer","description":"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).","format":"int32","nullable":true},"groupId":{"type":"integer","description":"The id of the group to assign the service instance to.","format":"int32","nullable":true},"note":{"maxLength":10000,"minLength":0,"type":"string","description":"A note on the service instance. Supports html formatted text including inline css styles.","nullable":true},"oneTimeCosts":{"maximum":1.7976931348623157e+308,"minimum":0,"type":"number","description":"One-time purchase costs of the instance in its life cycle to date.\nWhen set, overwrites the value of the provided offer for this service instance.","format":"double","nullable":true},"recurringCosts":{"maximum":1.7976931348623157e+308,"minimum":0,"type":"number","description":"The current recurring costs for the service instance.\nWhen set, overwrites the value of the provided offer for this service instance.","format":"double","nullable":true},"subscriptionPeriod":{"maximum":2147483647,"minimum":0,"type":"integer","description":"The minimum subscription period (in months) for the services instance.\nWhen set, overwrites the value of the provided offer for this service instance.","format":"int32","nullable":true},"subscriptionPeriodRenewal":{"maximum":2147483647,"minimum":0,"type":"integer","description":"Number of months a subscription is renewed after its expiration time if it has not been terminated.\nWhen set, overwrites the value of the provided offer for this service instance.","format":"int32","nullable":true},"activationDate":{"type":"string","description":"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.","format":"date-time","nullable":true},"expirationDate":{"type":"string","description":"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.\n\nThe expiration date must not be before the activation date.","format":"date-time","nullable":true},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"},"description":"Service instance metadata. Metadata can be used to store dynamic key value paired information on an instance.","nullable":true},"locationId":{"type":"integer","description":"The id of the location to assign the service instance to. Needs to be a valid location of the customer.\nNull will remove the location assignment.","format":"int32","nullable":true},"employeeId":{"type":"integer","description":"The id of the employee to assign the service instance to. Needs to be a valid employee of the customer.\nNull will remove the employee assignment.","format":"int32","nullable":true},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true}},"additionalProperties":false},"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"ServiceInstance":{"required":["id","self"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"location":{"$ref":"#/components/schemas/LocationReference"},"group":{"$ref":"#/components/schemas/GroupReference"},"employee":{"$ref":"#/components/schemas/EmployeeReference"},"activationDate":{"type":"string","description":"The date the service instance was activated.","format":"date-time","nullable":true},"lastModifiedDate":{"type":"string","description":"The date the service instance was last modified.","format":"date-time","nullable":true},"expirationDate":{"type":"string","description":"The date when the service instance should expire.","format":"date-time","nullable":true},"processStatus":{"type":"string","description":"The processing status of the service instance.","nullable":true},"active":{"type":"boolean","description":"True if the service instance is active, otherwise false."},"oneTimeCosts":{"type":"number","description":"One-time purchase costs of the instance in its life cycle to date.","format":"double"},"recurringCosts":{"type":"number","description":"The current recurring costs for the service instance. Only calculated for active instances.","format":"double"},"currencyCode":{"type":"string","description":"Currency in ISO 4217","nullable":true},"subscriptionPeriod":{"type":"integer","description":"The minimum subscription period (in months) for the services instance.","format":"int32","nullable":true},"subscriptionPeriodRenewal":{"type":"integer","description":"Number of months a subscription is renewed after its expiration time if it has not been terminated.","format":"int32","nullable":true},"note":{"type":"string","description":"A note on the service instance. Supports html formatted text including inline css styles.","nullable":true},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"},"description":"Service instance metadata. Metadata can be used to store dynamic key value paired information on an instance.","nullable":true},"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true},"costCenter":{"type":"string","description":"The name of the cost center to which the service instance belongs.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ServiceProductReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the service.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the service."},"category":{"type":"string","description":"The category of the service. Comes from the marketplace ProductDisplayGroup","nullable":true},"ean":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service. (Max. 50 characters)","nullable":true},"externalId":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service.","nullable":true},"supplierName":{"type":"string","description":"The supplier for this service product","nullable":true},"previewImageLink":{"type":"string","description":"Link to a small preview image for the product","nullable":true},"type":{"$ref":"#/components/schemas/ServiceProductType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductType":{"enum":["service","addon","foundation_service"],"type":"string","description":"Services can take on different types that define their meaning and process flows within the system."},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"GroupReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances":{"post":{"tags":["Sales | Service Instances"],"summary":"Create a new service instance","description":"Every service instance is based on a service and its offer. So an offer id needs to be provided.\nPlease use sales service and/or sales service offer POST endpoints to create the required information, if missing.\n\nTherefore please provide assignment information etc. regarding the configuration of the service in the portfolio.\n\nIt is only possible to create active service instance therefore an activation date needs to be provided.\n\nIt 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.","requestBody":{"description":"Information of the service instance to be created.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInstanceCreate"}}}},"responses":{"201":{"description":"Created: The created service instance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInstance"}}}},"400":{"description":"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.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: One of the given references (e.g. offer) can not be found."},"409":{"description":"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."}}}}}} ``` ## Retrieve a single service instance by its id > You can only access service instances that you provide. ```json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ServiceInstance":{"required":["id","self"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"location":{"$ref":"#/components/schemas/LocationReference"},"group":{"$ref":"#/components/schemas/GroupReference"},"employee":{"$ref":"#/components/schemas/EmployeeReference"},"activationDate":{"type":"string","description":"The date the service instance was activated.","format":"date-time","nullable":true},"lastModifiedDate":{"type":"string","description":"The date the service instance was last modified.","format":"date-time","nullable":true},"expirationDate":{"type":"string","description":"The date when the service instance should expire.","format":"date-time","nullable":true},"processStatus":{"type":"string","description":"The processing status of the service instance.","nullable":true},"active":{"type":"boolean","description":"True if the service instance is active, otherwise false."},"oneTimeCosts":{"type":"number","description":"One-time purchase costs of the instance in its life cycle to date.","format":"double"},"recurringCosts":{"type":"number","description":"The current recurring costs for the service instance. Only calculated for active instances.","format":"double"},"currencyCode":{"type":"string","description":"Currency in ISO 4217","nullable":true},"subscriptionPeriod":{"type":"integer","description":"The minimum subscription period (in months) for the services instance.","format":"int32","nullable":true},"subscriptionPeriodRenewal":{"type":"integer","description":"Number of months a subscription is renewed after its expiration time if it has not been terminated.","format":"int32","nullable":true},"note":{"type":"string","description":"A note on the service instance. Supports html formatted text including inline css styles.","nullable":true},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"},"description":"Service instance metadata. Metadata can be used to store dynamic key value paired information on an instance.","nullable":true},"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true},"costCenter":{"type":"string","description":"The name of the cost center to which the service instance belongs.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ServiceProductReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the service.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the service."},"category":{"type":"string","description":"The category of the service. Comes from the marketplace ProductDisplayGroup","nullable":true},"ean":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service. (Max. 50 characters)","nullable":true},"externalId":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service.","nullable":true},"supplierName":{"type":"string","description":"The supplier for this service product","nullable":true},"previewImageLink":{"type":"string","description":"Link to a small preview image for the product","nullable":true},"type":{"$ref":"#/components/schemas/ServiceProductType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductType":{"enum":["service","addon","foundation_service"],"type":"string","description":"Services can take on different types that define their meaning and process flows within the system."},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"GroupReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}":{"get":{"tags":["Sales | Service Instances"],"summary":"Retrieve a single service instance by its id","description":"You can only access service instances that you provide.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK: The requested service instance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInstance"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## PUT /v1/sales/service-instances/{instanceId} > Please use the PATCH route instead. ```json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ServiceInstanceUpdate":{"type":"object","properties":{"locationId":{"type":"integer","description":"The id of the location to assign the service instance to. Needs to be a valid location of the customer.\nNull will remove the location assignment.","format":"int32","nullable":true},"employeeId":{"type":"integer","description":"The id of the employee to assign the service instance to. Needs to be a valid employee of the customer.\nNull will remove the employee assignment.","format":"int32","nullable":true},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true}},"additionalProperties":false},"ServiceInstance":{"required":["id","self"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"location":{"$ref":"#/components/schemas/LocationReference"},"group":{"$ref":"#/components/schemas/GroupReference"},"employee":{"$ref":"#/components/schemas/EmployeeReference"},"activationDate":{"type":"string","description":"The date the service instance was activated.","format":"date-time","nullable":true},"lastModifiedDate":{"type":"string","description":"The date the service instance was last modified.","format":"date-time","nullable":true},"expirationDate":{"type":"string","description":"The date when the service instance should expire.","format":"date-time","nullable":true},"processStatus":{"type":"string","description":"The processing status of the service instance.","nullable":true},"active":{"type":"boolean","description":"True if the service instance is active, otherwise false."},"oneTimeCosts":{"type":"number","description":"One-time purchase costs of the instance in its life cycle to date.","format":"double"},"recurringCosts":{"type":"number","description":"The current recurring costs for the service instance. Only calculated for active instances.","format":"double"},"currencyCode":{"type":"string","description":"Currency in ISO 4217","nullable":true},"subscriptionPeriod":{"type":"integer","description":"The minimum subscription period (in months) for the services instance.","format":"int32","nullable":true},"subscriptionPeriodRenewal":{"type":"integer","description":"Number of months a subscription is renewed after its expiration time if it has not been terminated.","format":"int32","nullable":true},"note":{"type":"string","description":"A note on the service instance. Supports html formatted text including inline css styles.","nullable":true},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"},"description":"Service instance metadata. Metadata can be used to store dynamic key value paired information on an instance.","nullable":true},"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true},"costCenter":{"type":"string","description":"The name of the cost center to which the service instance belongs.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ServiceProductReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the service.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the service."},"category":{"type":"string","description":"The category of the service. Comes from the marketplace ProductDisplayGroup","nullable":true},"ean":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service. (Max. 50 characters)","nullable":true},"externalId":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service.","nullable":true},"supplierName":{"type":"string","description":"The supplier for this service product","nullable":true},"previewImageLink":{"type":"string","description":"Link to a small preview image for the product","nullable":true},"type":{"$ref":"#/components/schemas/ServiceProductType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductType":{"enum":["service","addon","foundation_service"],"type":"string","description":"Services can take on different types that define their meaning and process flows within the system."},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"GroupReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}":{"put":{"tags":["Sales | Service Instances"],"summary":"Please use the PATCH route instead.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"Information of the service instance to be updated.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInstanceUpdate"}}}},"responses":{"200":{"description":"OK: Returns the updated service instance.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInstance"}}}},"400":{"description":"Bad request: Body validation failed. See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"deprecated":true}}}} ``` ## Remove a service instance from the customers inventory > 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. ```json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}":{"delete":{"tags":["Sales | Service Instances"],"summary":"Remove a service instance from the customers inventory","description":"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. \nBehavior is the same as when the customer cancels the service and termination gets processed.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance to be removed.","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"processingDate","in":"query","description":"The date on which the deletion is processed. Value must not be in the future","schema":{"type":"string","format":"date-time"}}],"responses":{"204":{"description":"NoContent: Remove successful."},"400":{"description":"Bad request: Body validation failed. See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"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."}}}}}} ``` ## Update an existing service instance > Partial update via JSON Patch: only the paths you include change; omitted properties keep their current value.\ > \ ````json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"Operation":{"type":"object","properties":{"value":{"nullable":true},"path":{"type":"string","nullable":true},"op":{"type":"string","nullable":true},"from":{"type":"string","nullable":true}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}":{"patch":{"tags":["Sales | Service Instances"],"summary":"Update an existing service instance","description":"Partial update via JSON Patch: only the paths you include change; omitted properties keep their current value.\n","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"JSON patch object to update the service instance.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Operation"}}}}},"responses":{"204":{"description":"NoContent: Request has succeeded."},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied or resource does not exist anymore.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: Change not allowed by the service's portfolio context or the instance's process status, or the instance is a system product / removed / revoked. See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ```` ## Create a cancellation for a service instance > 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. ````json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ServiceInstanceCancellationCreate":{"type":"object","properties":{"scheduledProcessingDate":{"type":"string","description":"The date on which the cancellation order item should be automatically processed.\nWhen omitted the order item will not be processed automatically and must be processed manually.","format":"date","nullable":true}},"additionalProperties":false,"description":"Request body for creating a service instance cancellation."},"FulfillmentOrder":{"required":["customer","id","offer","order","orderedBy","self","service","status","transactionType"],"type":"object","properties":{"transactionType":{"$ref":"#/components/schemas/FulfillmentOrderTransactionType"},"status":{"$ref":"#/components/schemas/FulfillmentStatus"},"fulfillmentType":{"$ref":"#/components/schemas/FulfillmentType"},"isPreorder":{"type":"boolean","description":"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.","readOnly":true,"deprecated":true},"partnerNote":{"type":"string","description":"A note shared with the intermediary partner. (Only for orders placed by partner customers)","nullable":true},"offer":{"$ref":"#/components/schemas/ServiceOfferReference"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"options":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentServiceOption"},"description":"Reference to the ordered product option versions.","nullable":true},"order":{"$ref":"#/components/schemas/SalesOrderReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"orderedBy":{"$ref":"#/components/schemas/EmployeeFulfillmentReference"},"deliveryAddress":{"$ref":"#/components/schemas/Address"},"billingAddress":{"$ref":"#/components/schemas/Address"},"preferredProvisionDate":{"type":"string","description":"The preferred provision date.","format":"date-time","nullable":true},"serviceInstance":{"$ref":"#/components/schemas/ServiceInstanceReference"},"targetServiceInstance":{"$ref":"#/components/schemas/TargetServiceInstanceReference"},"assignments":{"$ref":"#/components/schemas/FulfillmentAssignment"},"bomItems":{"type":"array","items":{"$ref":"#/components/schemas/BomItem"},"description":"Items in the bom which are required to fulfill the order.","nullable":true},"totalRecurringPrice":{"type":"number","description":"Sum of the recurring prices of the service offer and the ordered options in this item.","format":"double"},"totalPurchasePrice":{"type":"number","description":"Sum of the purchase prices of the service offer and the ordered options in this item.","format":"double"},"id":{"type":"integer","description":"The identifier of the order.","format":"int64"},"externalId":{"type":"string","description":"The identifier of the order in an external app.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"FulfillmentOrderTransactionType":{"enum":["order","preorder","request","return","change","swap","cancellation"],"type":"string","description":"The action triggered by a fulfillment order."},"FulfillmentStatus":{"enum":["new","inprocess","ready-for-delivery","delivery-requested-outbound","in-delivery-outbound","delivered-outbound","delivery-returned-outbound","processed","cancelled"],"type":"string","description":"Status of the fulfillment process."},"FulfillmentType":{"enum":["in-house","dropshipping"],"type":"string","description":"Types of fulfillment to complete a customer order."},"ServiceOfferReference":{"required":["currency","id","purchasePrice","recurringPrice","self","subscriptionPeriod","type"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the offer in the system.","format":"int32"},"type":{"$ref":"#/components/schemas/OfferType"},"purchasePrice":{"maximum":1.7976931348623157e+308,"minimum":0,"type":"number","description":"The price charged only once after providing the item.","format":"double"},"recurringPrice":{"maximum":1.7976931348623157e+308,"minimum":0,"type":"number","description":"The price charged monthly after providing the item for the subscription period","format":"double"},"currency":{"minLength":1,"type":"string","description":"Currency in ISO 4217"},"subscriptionPeriod":{"maximum":2147483647,"minimum":0,"type":"integer","description":"The minimum subscription period (in months) for rental offers.","format":"int32"},"name":{"type":"string","description":"Name of the offer","nullable":true},"externalId":{"type":"string","description":"Value to identify the offer in other systems. E.g. when another system is the source of this offer.","nullable":true},"isDefault":{"type":"boolean","description":"Indicates if this offer is a default offer for the service."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"OfferType":{"enum":["rental","lease","purchase","subscription","leasing"],"type":"string"},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ServiceProductReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the service.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the service."},"category":{"type":"string","description":"The category of the service. Comes from the marketplace ProductDisplayGroup","nullable":true},"ean":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service. (Max. 50 characters)","nullable":true},"externalId":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service.","nullable":true},"supplierName":{"type":"string","description":"The supplier for this service product","nullable":true},"previewImageLink":{"type":"string","description":"Link to a small preview image for the product","nullable":true},"type":{"$ref":"#/components/schemas/ServiceProductType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductType":{"enum":["service","addon","foundation_service"],"type":"string","description":"Services can take on different types that define their meaning and process flows within the system."},"FulfillmentServiceOption":{"required":["offer","option","version"],"type":"object","properties":{"offer":{"$ref":"#/components/schemas/SalesVersionOfferReference"},"option":{"$ref":"#/components/schemas/ProductOptionReference"},"version":{"$ref":"#/components/schemas/ProductOptionVersionReference"}},"additionalProperties":false},"SalesVersionOfferReference":{"required":["id","purchasePrice","recurringPrice","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the offer in the system.","format":"int64"},"purchasePrice":{"maximum":1.7976931348623157e+308,"minimum":0,"type":"number","description":"The price charged only once after providing the item.","format":"double"},"recurringPrice":{"maximum":1.7976931348623157e+308,"minimum":0,"type":"number","description":"The price charged monthly after providing the item for the subscription period","format":"double"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ProductOptionReference":{"required":["self"],"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the option","format":"int32"},"name":{"type":"string","description":"Display name of the option","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ProductOptionVersionReference":{"required":["self"],"type":"object","properties":{"id":{"type":"integer","description":"Identifier of the version","format":"int32"},"name":{"type":"string","description":"Display name of the version","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SalesOrderReference":{"required":["created","id","orderNumber","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the order is also the order number.","format":"int64"},"customerOrderNumber":{"maxLength":100,"minLength":0,"type":"string","description":"Order reference number from the customer","nullable":true},"orderNumber":{"minLength":1,"type":"string","description":"Unique reference number of the sales order."},"created":{"type":"string","description":"The date and time when the order was placed. (ISO 8601 format)","format":"date-time"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"EmployeeFulfillmentReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"phoneBusiness":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees workplace.","nullable":true},"phoneMobile":{"maxLength":50,"minLength":0,"type":"string","description":"The phone number of the employees business mobile phone.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"Address":{"required":["id","self"],"type":"object","properties":{"line1":{"maxLength":100,"minLength":0,"type":"string","description":"First line of the address. e.g. company name or P.O. box.","nullable":true},"street":{"maxLength":100,"minLength":0,"type":"string","description":"The street name of the address.","nullable":true},"number":{"maxLength":30,"minLength":0,"type":"string","description":"The alphanumeric house number in the street.","nullable":true},"addition":{"maxLength":1500,"minLength":0,"type":"string","description":"Addition to the address (line 3) to provide further information for delivery.","nullable":true},"city":{"maxLength":100,"minLength":0,"type":"string","description":"The city name of the address.","nullable":true},"postalCode":{"maxLength":30,"minLength":0,"type":"string","description":"The alphanumeric postal code or zip of the address.","nullable":true},"countryCode":{"maxLength":2,"minLength":0,"type":"string","description":"ISO-3166-1 code of the country.","nullable":true},"regionCode":{"maxLength":10,"minLength":0,"type":"string","description":"ISO-3166-2 code of the region / administrative area. Required e.g. in USA, Canada, Australia or Italy.","nullable":true},"regionName":{"maxLength":100,"minLength":0,"type":"string","description":"Name of the region / administrative area (if no ISO code is given/existing).","nullable":true},"dependentLocality":{"maxLength":200,"minLength":0,"type":"string","description":"A dependent locality is an address element that distinguishes a premise when an address thoroughfare appears more than once in the same post town. PAF holds details of approximately 30,000 localities within the UK.","nullable":true},"phoneNumber":{"maxLength":50,"minLength":0,"type":"string","description":"Phone number of the address. Used primarily for delivery purposes.","nullable":true},"id":{"type":"integer","description":"The id to identify the address in the system.","format":"int64"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"Postal address for the shipment of goods or invoices."},"ServiceInstanceReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true},"costCenter":{"type":"string","description":"The name of the cost center to which the service instance belongs.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"TargetServiceInstanceReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"},"description":"Service instance metadata. Metadata can be used to store dynamic key value paired information on an instance.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"FulfillmentAssignment":{"type":"object","properties":{"location":{"$ref":"#/components/schemas/LocationReference"},"employee":{"$ref":"#/components/schemas/EmployeeFulfillmentReference"}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"BomItem":{"required":["quantity"],"type":"object","properties":{"quantity":{"maximum":2147483647,"minimum":1,"type":"integer","description":"Quantity of the product in the bill of materials","format":"int32","default":1},"product":{"$ref":"#/components/schemas/ProductReference"}},"additionalProperties":false},"ProductReference":{"required":["id","name","partNumber","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the product.","format":"int64"},"name":{"minLength":1,"type":"string","description":"The name of the product."},"partNumber":{"minLength":1,"type":"string","description":"The manufacturer part number of the product."},"externalId":{"type":"string","description":"The id of the product in an external application like an ERP. Can be used for synchronization correlation.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}/cancel":{"post":{"tags":["Sales | Service Instances"],"summary":"Create a cancellation for a service instance","description":"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```.\n\nYou can only cancel service instances that you provide.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance to cancel.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"Cancellation details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInstanceCancellationCreate"}}}},"responses":{"201":{"description":"Created: The created cancellation fulfillment order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentOrder"}}}},"400":{"description":"Bad request: Body validation failed. See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: Service instance is not in a cancellable state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ```` ## List metadata of a service instance > Retrieves the metadata of a service instance as a list of key/value pairs.\ > \ > You can only access service instances that you provide. ```json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}/metadata":{"get":{"tags":["Sales | Service Instances"],"summary":"List metadata of a service instance","description":"Retrieves the metadata of a service instance as a list of key/value pairs.\n\nYou can only access service instances that you provide.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"200":{"description":"OK: Service instance meta data.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"}}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Create or update the metadata of a service instance > 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. ````json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}/metadata":{"put":{"tags":["Sales | Service Instances"],"summary":"Create or update the metadata of a service instance","description":"The provided request body has to be a list of key/value pairs (see ```schema``` below).\n\nA 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.\n\nYou can only update metadata which was created by your provider entity.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"The metadata to create or update.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"}}}}},"responses":{"204":{"description":"NoContent: Request has succeeded."},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ```` ## Delete all metadata of a service instance > You can only delete metadata which was created by your provider entity. ```json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}/metadata":{"delete":{"tags":["Sales | Service Instances"],"summary":"Delete all metadata of a service instance","description":"You can only delete metadata which was created by your provider entity.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance.","required":true,"schema":{"type":"integer","format":"int32"}}],"responses":{"204":{"description":"NoContent: Request has succeeded."},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Retrieve a metadata entry of a service instance by its specified key > 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. ```json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}/metadata/{key}":{"get":{"tags":["Sales | Service Instances"],"summary":"Retrieve a metadata entry of a service instance by its specified key","description":"Retrieves a single metadata entry of a service instance as a key/value pair.\n\nYou can only access metadata of service instances that you provide.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance.","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"key","in":"path","description":"The key of the metadata value to retrieve.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK: Service instance meta data value.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataEntry"}}}},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Create or update a single metadata entry of a service instance > 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. ````json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"MetadataValue":{"required":["value"],"type":"object","properties":{"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}/metadata/{key}":{"put":{"tags":["Sales | Service Instances"],"summary":"Create or update a single metadata entry of a service instance","description":"The provided request body has to be a metadata value(see ```schema``` below).\n\nA 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.\n\nYou can only update metadata which was created by your provider entity.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance.","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"key","in":"path","description":"The key of the metadata value to create or update.","required":true,"schema":{"maxLength":150,"minLength":0,"type":"string"}}],"requestBody":{"description":"The value to create or update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataValue"}}}},"responses":{"204":{"description":"NoContent: Request has succeeded."},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ```` ## Delete a single metadata entry of a service instance. > You can only delete metadata which was created by your provider entity. ```json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}/metadata/{key}":{"delete":{"tags":["Sales | Service Instances"],"summary":"Delete a single metadata entry of a service instance.","description":"You can only delete metadata which was created by your provider entity.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance.","required":true,"schema":{"type":"integer","format":"int32"}},{"name":"key","in":"path","description":"The key of the metadata value to delete.","required":true,"schema":{"type":"string"}}],"responses":{"204":{"description":"NoContent: Request has succeeded."},"400":{"description":"Bad request: See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key or expired access token.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ``` ## Change the service/offer of a service instance > Re-points a service instance to a different service and offer of the same supplier, recording the reason in the change history.\ > \ > The target service must have the same configuration type as the current one (simple → simple, dynamic → dynamic).\ > \ > The new price snapshot is taken from the target offer. Provide \`\`\`recurringCosts\`\`\` and/or \`\`\`oneTimeCosts\`\`\` to override it for this instance.\ > \ > For dynamic services the existing option instances are removed and the target service's mandatory and system options are instantiated with their default version. Use \`\`\`optionVersionIds\`\`\` to pick different versions.\ > \ > You can only change service instances that you provide. ````json {"openapi":"3.0.4","info":{"title":"Equipme Supplier API","version":"v1"},"tags":[{"name":"Sales | Service Instances"}],"security":[{"ApiKey":[]}],"components":{"securitySchemes":{"ApiKey":{"type":"apiKey","description":"Required for authorization in every request. You can request an API-Key for your tenant in the integrations section of the equipme App.","name":"X-API-KEY","in":"header"}},"schemas":{"ServiceChangeRequest":{"required":["targetOfferId","targetServiceId"],"type":"object","properties":{"targetServiceId":{"type":"integer","description":"Id of the target service (SOURCING.Product) to re-point the instance to.","format":"int32"},"targetOfferId":{"type":"integer","description":"Id of the target SOURCING.ProductOffer (must belong to TargetServiceId).","format":"int32"},"reason":{"type":"string","description":"Free-text reason recorded in the change history.","nullable":true},"optionVersionIds":{"type":"array","items":{"type":"integer","format":"int32"},"description":"Optional option versions to set on the instance, for dynamic target services.\nMandatory and system options of the target service are always instantiated with their default version;\na version given here replaces the default for its option and can additionally pull in an optional option.\nEach version must belong to an option of the target service and have an offer under the target offer.","nullable":true},"recurringCosts":{"maximum":1.7976931348623157e+308,"minimum":0,"type":"number","description":"Optional recurring price for the new offer snapshot. When omitted, the target offer's current recurring price is used.","format":"double","nullable":true},"oneTimeCosts":{"maximum":1.7976931348623157e+308,"minimum":0,"type":"number","description":"Optional one-time price for the new offer snapshot. When omitted, the target offer's current purchase price is used.","format":"double","nullable":true}},"additionalProperties":false,"description":"Request body for changing the service/offer of a simple service instance."},"ServiceInstance":{"required":["id","self"],"type":"object","properties":{"supplier":{"$ref":"#/components/schemas/SupplierReference"},"service":{"$ref":"#/components/schemas/ServiceProductReference"},"customer":{"$ref":"#/components/schemas/CustomerReference"},"location":{"$ref":"#/components/schemas/LocationReference"},"group":{"$ref":"#/components/schemas/GroupReference"},"employee":{"$ref":"#/components/schemas/EmployeeReference"},"activationDate":{"type":"string","description":"The date the service instance was activated.","format":"date-time","nullable":true},"lastModifiedDate":{"type":"string","description":"The date the service instance was last modified.","format":"date-time","nullable":true},"expirationDate":{"type":"string","description":"The date when the service instance should expire.","format":"date-time","nullable":true},"processStatus":{"type":"string","description":"The processing status of the service instance.","nullable":true},"active":{"type":"boolean","description":"True if the service instance is active, otherwise false."},"oneTimeCosts":{"type":"number","description":"One-time purchase costs of the instance in its life cycle to date.","format":"double"},"recurringCosts":{"type":"number","description":"The current recurring costs for the service instance. Only calculated for active instances.","format":"double"},"currencyCode":{"type":"string","description":"Currency in ISO 4217","nullable":true},"subscriptionPeriod":{"type":"integer","description":"The minimum subscription period (in months) for the services instance.","format":"int32","nullable":true},"subscriptionPeriodRenewal":{"type":"integer","description":"Number of months a subscription is renewed after its expiration time if it has not been terminated.","format":"int32","nullable":true},"note":{"type":"string","description":"A note on the service instance. Supports html formatted text including inline css styles.","nullable":true},"metadata":{"type":"array","items":{"$ref":"#/components/schemas/MetadataEntry"},"description":"Service instance metadata. Metadata can be used to store dynamic key value paired information on an instance.","nullable":true},"id":{"type":"integer","description":"The id to identify the service instance in the system.","format":"int32"},"inventoryNumber":{"maxLength":50,"minLength":0,"type":"string","description":"The inventory number of the service instance.","nullable":true},"costCenter":{"type":"string","description":"The name of the cost center to which the service instance belongs.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"SupplierReference":{"required":["id","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the supplier.","format":"int64"},"name":{"type":"string","description":"The name of the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"type":"object","properties":{"href":{"type":"string","nullable":true},"method":{"type":"string","nullable":true}},"additionalProperties":false},"ServiceProductReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the service.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the service."},"category":{"type":"string","description":"The category of the service. Comes from the marketplace ProductDisplayGroup","nullable":true},"ean":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service. (Max. 50 characters)","nullable":true},"externalId":{"type":"string","description":"Value to identify the service in other systems. E.g. when an other system is the source of this service.","nullable":true},"supplierName":{"type":"string","description":"The supplier for this service product","nullable":true},"previewImageLink":{"type":"string","description":"Link to a small preview image for the product","nullable":true},"type":{"$ref":"#/components/schemas/ServiceProductType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ServiceProductType":{"enum":["service","addon","foundation_service"],"type":"string","description":"Services can take on different types that define their meaning and process flows within the system."},"CustomerReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the customer.","format":"int32"},"name":{"minLength":1,"type":"string","description":"The name of the customer."},"customerNumber":{"type":"string","description":"Optional identifier of the customer defined by the supplier.","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"LocationReference":{"required":["id","name","self","type"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the company location.","format":"int32"},"name":{"maxLength":100,"minLength":0,"type":"string","description":"The name of the company location."},"type":{"$ref":"#/components/schemas/LocationType"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false,"description":"A location can either be a company location or a work from home location."},"LocationType":{"enum":["location","warehouse","remoteWork"],"type":"string","description":"The type of location."},"GroupReference":{"required":["id","name","self"],"type":"object","properties":{"id":{"type":"integer","description":"The id to identify the group in the system.","format":"int32"},"name":{"maxLength":50,"minLength":0,"type":"string","description":"The name of the group."},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"EmployeeReference":{"required":["id","self","username"],"type":"object","properties":{"id":{"type":"integer","description":"The identifier of the employee.","format":"int32"},"firstName":{"maxLength":100,"minLength":0,"type":"string","description":"The first/given name of the employee.","nullable":true},"lastName":{"maxLength":100,"minLength":0,"type":"string","description":"The last/family name of the employee.","nullable":true},"fullName":{"maxLength":150,"minLength":0,"type":"string","description":"Combination of last and firstname","nullable":true,"readOnly":true},"email":{"maxLength":100,"minLength":0,"type":"string","description":"The contact and login mail address.","nullable":true},"username":{"maxLength":100,"minLength":0,"pattern":"^[a-zA-Z0-9.!#$%&’*+/=?^_`{|}~-]+@[a-zA-Z0-9-]+(?:\\.[a-zA-Z0-9-]+)*\\.[a-zA-Z]{2,}$","type":"string","description":"The username to log in to the app. The value has to be an e-mail address."},"costCenter":{"maxLength":100,"minLength":0,"type":"string","description":"The cost center of the employee.","nullable":true},"costCenterId":{"type":"integer","description":"The identifier of the cost center.","format":"int32","nullable":true},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"MetadataEntry":{"required":["key","value"],"type":"object","properties":{"key":{"maxLength":150,"minLength":0,"type":"string","description":"Key of the metadata entry."},"value":{"maxLength":500,"minLength":0,"type":"string","description":"The value of the metadata entry."},"scope":{"$ref":"#/components/schemas/ServiceInstanceMetadataScope"}},"additionalProperties":false},"ServiceInstanceMetadataScope":{"enum":["public","internal"],"type":"string","description":"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"},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/sales/service-instances/{instanceId}/service-change":{"post":{"tags":["Sales | Service Instances"],"summary":"Change the service/offer of a service instance","description":"Re-points a service instance to a different service and offer of the same supplier, recording the reason in the change history.\n\nThe target service must have the same configuration type as the current one (simple → simple, dynamic → dynamic).\n\nThe new price snapshot is taken from the target offer. Provide ```recurringCosts``` and/or ```oneTimeCosts``` to override it for this instance.\n\nFor dynamic services the existing option instances are removed and the target service's mandatory and system options are instantiated with their default version. Use ```optionVersionIds``` to pick different versions.\n\nYou can only change service instances that you provide.","parameters":[{"name":"instanceId","in":"path","description":"The identifier of the service instance to change.","required":true,"schema":{"type":"integer","format":"int32"}}],"requestBody":{"description":"Service change details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceChangeRequest"}}}},"responses":{"200":{"description":"OK: The refreshed service instance. The created service change id is returned in the X-Service-Change-Id header.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServiceInstance"}}}},"400":{"description":"Bad request: Body validation failed. See response message for details.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized: Invalid api key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden: Resource access denied.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"NotFound: Requested resource could not be found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"409":{"description":"Conflict: Service instance is not in a changeable state.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}} ```` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://hub.equipme.io/development/api-reference-pro/sales-or-service-instances.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.