Order terminals

Use our Management API to order payment terminals and accessories.

The Management API lets you order terminals and accessories for delivery to a location of your choice using API requests instead of the Customer Area.

Requirements

Before you begin, take into account the following requirements, limitations, and preparations.

Requirement	Description
Integration type	A point-of-sale integration with Adyen.
API credentials	You must have an API credential with an API key and the following roles: Management API—Terminal ordering read Management API—Terminal ordering read and write If you have a Terminal API integration with cloud-based communications, you can use the existing API key that you use for Terminal API requests.
Webhooks	Optionally subscribe to Terminal order update webhooks.
Limitations	Note the following: You can only create orders for live terminals using the Management API. To order test terminals, you need to submit a sales order in your test Customer Area. Requests to live Management API endpoints related to terminal orders are subject to rate limits.

Products and orders

You can order products for a company account or a merchant account. A product can be:

A box containing a payment terminal and default items like a power cable.
An accessory, like a privacy shield, a stylus pen, or a replacement power cable.

Apart from the products, an order includes:

A billing entity for the company or merchant account. This is where we charge the order to. We create billing entities for you based on the details you provided when you applied for the accounts.
A shipping location for the company or merchant account. This is where we send the order. A shipping location is linked to a company account or a merchant account. You create shipping locations yourself.

Get the product ID

An order for terminal products must contain the IDs of the products you want to order. To retrieve those IDs and decide what to order:

Get the ID of the account you want to order products for. You need to specify that ID in the URL of later requests.
- For the company ID, make a GET /companies request.
- For the merchant ID, make a GET /merchants request.
Get a list of payment terminal models you can order for your company or merchant account. Use the following endpoints:
- GET /companies/{companyId}/terminalModels
- GET /merchants/{merchantId}/terminalModels
The response returns the id and name of the various models. You can use the id as a query parameter to filter the product list in the next step.

Get a list of products you can order for your company or merchant account. Use the following endpoints, with the country as a query parameter:

These are the query parameters to filter the paginated response:

Query parameter	Required	Result
country		Returns products for the country/region specified by a two-letter country code in ISO 3166-1 alpha-2 format.
terminalModelId		Returns products for the terminal model specified by its ID. This is the id returned in the `/terminalModels` response. The product list will show the details of the box containing the terminal and all accessories you can order for that terminal model.
offset		Returns products shown on the specified page.
limit		The number of products to have on a page.

The following example retrieves a list of all products related to the V400m payment terminal that can be ordered for a merchant account in France.

When you receive the response, save the id values of the products you want to order.

The next example shows the response for the GET merchants/{merchantId}/terminalProducts?country=FR&terminalModelId=Verifone.V400m request (prices have been changed to 0.00 in the example).

Get the billing entity ID

An order for terminal products must contain the ID of a billing entity. This is the legal entity where we charge the order to. We create billing entities for you based on the details provided when you applied for your company and merchant accounts.

When ordering products in Brazil, you do not need to provide a billing entity ID.

Get the billing entity ID for your company or merchant account. Use the following endpoints:
- GET /companies/{companyId}/billingEntities for the billing entities of the company and all merchant accounts belonging to the company.
- GET /merchants/{merchantId}/billingEntities for the billing entities of the merchant account.
You can filter the response using the name of the billing entity as the query parameter:
When you receive the response, save the id of the billing entity to use in your order. The response also returns the name, taxId (VAT number) and contact details for each billing entity.

Get the shipping location ID

An order for terminal products must contain the ID of a shipping location. This is the street address of the location where you want us to send the order to.

New shipping location

To create a shipping location for your company or merchant account, use the following endpoints:

Specify the following parameters in the request body:

Parameter	Description
name	A unique reference that lets you recognize the location.
contact	Name and phone number of the individual who can be contacted about the shipment.
address	Where to send the order.

When you receive the response, note the following details:
- id: the generated shipping location ID, for use in an order for terminal products.
- name: your reference for this location. You can use this to filter the list of shipping locations.

If your next step after creating a new shipping location is to create an order for the new location, wait a few seconds before sending the order creation request.

Existing shipping locations

To get a list of existing shipping locations for your company or merchant account, use the following endpoints:

You can filter the paginated response using the following query parameters:

Parameter	Description
name	Filters the list by your reference to the shipping location.
offset	Returns locations starting from this offset.
limit	Sets a limit for the number of locations to 3return.

When you receive the response, save the id of the shipping location to use in your order.

Create a terminal order

Use this request to order live terminals for your company or merchant account.

Requests to the Management API test endpoint do not create actual orders for test terminals. To order test terminals, you need to submit a sales order in your test Customer Area.

Make sure that you have the following details:
- The IDs of the products you want to order.
- The ID of the billing entity.
- The ID of the shipping location.
If the order includes a new shipping location, wait a few seconds after creating the new location before sending the order creation request.

To create an order for your company or merchant account, use the following endpoints:

Specify the following parameters in the request body:

Parameter	Required	Description
customerOrderReference		Your purchase order number. This will be printed on the packing list.
billingEntityId		ID of the billing entity for the company or merchant account. When ordering products in Brazil, you do not need to include the `billingEntityId` in the request.
shippingLocationId		ID of the shipping location where we need to send the order.
items		An array listing the `id` and `quantity` of each product you want to order.
taxId		Tax number (VAT number) of the billing entity. Specify this parameter when the shipping location and the billing entity are in different countries/regions.

The next example places an order for one V400m terminal and 20 receipt rolls.

The response echoes the parameters you provided and additionally includes the id and status of your order, the date and time you placed the order, and the full details of the billing entity and the shipping location.

When an order reaches the status Shipped, the response also includes a URL where you can track your order.

Terminal order updates

To stay informed about your order, you can subscribe to Terminal order update webhooks. These webhooks are triggered at certain steps in the logistical process. The webhooks contain information such as shipment date, terminal serial numbers, and track & trace number. We send these platform webhooks as an HTTP callback (webhook) to your server.

We also keep you up to date on the status of your order through email messages and in your Customer Area > Orders and returns.

Manage orders

You can view , update, and cancel orders using API requests. However, updating and canceling is only allowed while the order has the status Placed. This indicates we haven't started processing the order yet.

View orders

You can use the /terminalOrders endpoint to check which orders can still be updated or cancelled, and to get the ID of those orders. To keep up to date on the progress of your order, we recommend using Terminal order update webhooks.

List of orders

To get the details of all orders for your company or merchant account, use the following endpoints:

You can filter the paginated response using the following query parameters:

Parameter	Description
customerOrderReference	Returns the details of the specified purchase order number.
status	Returns orders with the specified status. Possible values (not case-sensitive): Placed, Confirmed, Cancelled, Shipped, Delivered.
offset	Returns the orders shown on the specified page.
limit	The number of orders to have on a page.

The response returns an array of orders sorted by order date in ascending order. For each order, all order details are included.

Individual order

To get the details of an individual order for your company or merchant account, use the following endpoints:
- GET /companies/{companyId}/terminalOrders/{orderId}
- GET /merchants/{merchantId}/terminalOrders/{orderId}
The response returns all order details.

Update an order

While an order has the status Placed, you can change the order items, the shipping location, and the billing entity. The request body only needs to contain what you want to change. However, to update the items array, you need to replace the entire array. For example, let's assume the array has three items. To remove one item, the array must include the remaining two items. Or to add one item, the array must include all four items.

Get the ID of the order you want to update and check that the order has the status Placed.

To update the order for your company or merchant account, use the following endpoints:

Specify the following optional parameters in the request body as needed:

Parameter	Description
billingEntityId	ID of the billing entity for the company or merchant account. When ordering products in Brazil, you do not need to include the `billingEntityId` in the request.
shippingLocationId	ID of the shipping location where we need to send the order.
items	An array listing the `id` and `quantity` of each product you want to order. To remove an item, specify all remaining items. To add an item, specify all items already in the order plus the additional item.

The next request removes the 20 receipt rolls from our example order 7219627091701347 by listing only the remaining order item, and changes the billing entity.

The response returns all order details.

Cancel an order

While an order has the status Placed, you can revoke the order.

Get the ID of the order you want to cancel and check that the order has the status Placed.
To cancel an order for your company or merchant account, use the following endpoints:
- POST /companies/{companyId}/terminalOrders/{orderId}/cancel
- POST /merchants/{merchantId}/terminalOrders/{orderId}/cancel
Do not specify a request body.

The next request cancels our example order 7219627091701347.
The response returns all order details, but now the status is changed to Cancelled.