> 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-app/fulfillment-or-orders.md).
# Fulfillment | Orders
## List fulfillment orders of your customers
> A fulfillment order represents a single order of a service or cancellation or change of an existing service instance (subscription).\
> \
> These orders need to be fulfilled to process the lifecycle of the service instances.\
> \
> For example, use the \`\`\`status\`\`\` filter to get open fulfillment orders that you then can process through the \transition route\.\
> \
> You can only access orders of customers of your provider entity.
````json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Fulfillment | Orders"}],"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":{"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."},"FulfillmentOrderTransactionType":{"enum":["order","return","change","swap","cancellation"],"type":"string","description":"The action triggered by a fulfillment order."},"FulfillmentOrderList":{"required":["items","self","total"],"type":"object","properties":{"previous":{"$ref":"#/components/schemas/ResourceLink"},"next":{"$ref":"#/components/schemas/ResourceLink"},"items":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentOrder"},"description":"The list of result items."},"total":{"type":"integer","description":"The total number of items.","format":"int32"},"self":{"$ref":"#/components/schemas/ResourceLink"}},"additionalProperties":false},"ResourceLink":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","nullable":true}},"additionalProperties":false},"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."},"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},"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"},"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/fulfillment/orders":{"get":{"tags":["Fulfillment | Orders"],"summary":"List fulfillment orders of your customers","description":"A fulfillment order represents a single order of a service or cancellation or change of an existing service instance (subscription).\n\nThese orders need to be fulfilled to process the lifecycle of the service instances.\n\nFor example, use the ```status``` filter to get open fulfillment orders that you then can process through the transition route.\n\nYou can only access orders of customers of your provider entity.","parameters":[{"name":"customers","in":"query","description":"Filter the orders by one or more customer ids or names.","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"services","in":"query","description":"Filter the orders by one or more ordered service ids.","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"status","in":"query","description":"Filter the orders by status.","schema":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentStatus"}}},{"name":"transactionTypes","in":"query","description":"Filter by one or more transaction types.","schema":{"type":"array","items":{"$ref":"#/components/schemas/FulfillmentOrderTransactionType"}}},{"name":"order","in":"query","description":"Filter by the order number of the sales order.","schema":{"type":"string"}},{"name":"externalIds","in":"query","description":"Filter by one or more external ids.","schema":{"type":"array","items":{"type":"string"}}},{"name":"serviceCategories","in":"query","description":"Filter by one or more service categories based on their id.","schema":{"type":"array","items":{"type":"integer","format":"int32"}}},{"name":"after","in":"query","description":"Filter the orders created after the specified date.","schema":{"type":"string","format":"date-time"}},{"name":"before","in":"query","description":"Filter the orders created before the specified date.","schema":{"type":"string","format":"date-time"}},{"name":"sortBy","in":"query","description":"Sort the results by a given criterion (customer|date).","schema":{"type":"string","default":"date"}},{"name":"sortOrder","in":"query","description":"Sort the results in a given order (asc|desc).","schema":{"type":"string","default":"desc"}},{"name":"offset","in":"query","description":"Specifies the index of the first result to return","schema":{"type":"integer","format":"int32","default":0}},{"name":"limit","in":"query","description":"Specifies the maximum number of results to return (min: 1; max: 1000)","schema":{"type":"integer","format":"int32","default":100}}],"responses":{"200":{"description":"OK: List of fulfillment orders.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentOrderList"}}}},"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"}}}}}}}}}
````
## GET /v1/fulfillment/orders/{orderId}
> Retrieve a single fulfillment order by its id.
```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Fulfillment | Orders"}],"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":{"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."},"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","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":{"required":["href"],"type":"object","properties":{"href":{"minLength":1,"type":"string","description":"The target resource URI."},"method":{"type":"string","description":"The HTTP method to use for the request.","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/fulfillment/orders/{orderId}":{"get":{"tags":["Fulfillment | Orders"],"summary":"Retrieve a single fulfillment order by its id.","parameters":[{"name":"orderId","in":"path","description":"The identifier of the fulfillment order.","required":true,"schema":{"type":"integer","format":"int64"}}],"responses":{"200":{"description":"OK: The requested fulfillment order.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentOrder"}}}},"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"}}}}}}}}}
```
## PUT /v1/fulfillment/orders/{orderId}
> Update a fulfillment order regarding context information like the external id. To update the status see transition endpoint. (deprecated - please use the PATCH route instead)
````json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Fulfillment | Orders"}],"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":{"FulfillmentOrderUpdate":{"type":"object","properties":{"externalId":{"maxLength":100,"minLength":0,"type":"string","description":"The identifier of the order in an external app. Note: ```null``` value will be ignored on update. Set to empty string to clear a current value.","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/fulfillment/orders/{orderId}":{"put":{"tags":["Fulfillment | Orders"],"summary":"Update a fulfillment order regarding context information like the external id. To update the status see transition endpoint. (deprecated - please use the PATCH route instead)","parameters":[{"name":"orderId","in":"path","description":"The identifier of the order.","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"description":"The order data to update.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentOrderUpdate"}}}},"responses":{"204":{"description":"NoContent: Update 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 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: Request conflicts with the current state of the server.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"deprecated":true}}}}
````
## PATCH /v1/fulfillment/orders/{orderId}
> Patch a fulfillment order regarding context information like the external id. To update the status see transition endpoint.
```json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Fulfillment | Orders"}],"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/fulfillment/orders/{orderId}":{"patch":{"tags":["Fulfillment | Orders"],"summary":"Patch a fulfillment order regarding context information like the external id. To update the status see transition endpoint.","parameters":[{"name":"orderId","in":"path","description":"The identifier of the order.","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"description":"The order data to patch.","content":{"application/json":{"schema":{"type":"array","items":{"$ref":"#/components/schemas/Operation"}}}}},"responses":{"204":{"description":"NoContent: Patch 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 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"}}}}}}}}}
```
## Update the fulfillment status of an order
> To process the status of an order, cancellation or change, post a transition. This will process the lifecycle status of the related service instance (subscription).\
> \
> See the \`\`\`schema\`\`\` of the request body below for allowed actions in the transition.\
> \
> You can only access orders of customers of your provider entity.
````json
{"openapi":"3.0.4","info":{"title":"Equipme Customer API","version":"v1"},"tags":[{"name":"Fulfillment | Orders"}],"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":{"FulfillmentTransition":{"required":["action"],"type":"object","properties":{"action":{"$ref":"#/components/schemas/FulfillmentAction"},"activationDate":{"type":"string","description":"The (UTC) date on which the service should be activated (time component is ignored). Only applicable for the `complete` action.\nIf not provided, the service is activated immediately upon completion.","format":"date-time","nullable":true}},"additionalProperties":false},"FulfillmentAction":{"enum":["process","dispatchDelivery","rejectDelivery","confirmDelivery","processReturnedItem","complete","completeReturnDecommission","cancel"],"type":"string","description":"The action to take on the fulfillment order."},"ErrorResponse":{"type":"object","properties":{"errorCode":{"type":"string","nullable":true},"errorDescription":{"type":"string","nullable":true},"data":{"nullable":true}},"additionalProperties":false}}},"paths":{"/v1/fulfillment/orders/{orderId}/transitions":{"post":{"tags":["Fulfillment | Orders"],"summary":"Update the fulfillment status of an order","description":"To process the status of an order, cancellation or change, post a transition. This will process the lifecycle status of the related service instance (subscription).\n\nSee the ```schema``` of the request body below for allowed actions in the transition.\n\nYou can only access orders of customers of your provider entity.","parameters":[{"name":"orderId","in":"path","description":"The identifier of the order.","required":true,"schema":{"type":"integer","format":"int64"}}],"requestBody":{"description":"The transition to update the order status. See schema enum below for allowed actions.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FulfillmentTransition"}}}},"responses":{"204":{"description":"NoContent: Update 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 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: Request conflicts with the current state of the server.","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:
```
GET https://hub.equipme.io/development/api-reference-app/fulfillment-or-orders.md?ask=
```
The question should be specific, self-contained, and written in natural language.
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.