Api Reference

Orders

On this page, we'll dive into the different order endpoints you can use to manage orders programmatically.

The order model

The order model contains all the information about your orders, including the order details, customer information, line items, and tax information.

Properties

Name	Type	Description
`id`	`string`	Unique identifier for the order (starts with `order_`).
`resource`	`string`	The resource type. Always `order`.
`merchantId`	`string`	ID of the merchant that owns this order.
`customerId`	`string`	ID of the customer who made this purchase.
`testmode`	`boolean`	Whether this order is in test mode.
`metadata`	`object \| null`	Arbitrary key-value metadata for your application.
`paymentMethod`	`string \| null`	Payment method used for this order (e.g., `ideal`, `creditcard`, `bancontact`, `paypal`).
`status`	`string`	The current status of the order. Can be `created`, `pending`, `paid`, `canceled`, or `expired`.
`invoiceNumber`	`string \| null`	Invoice number for this order (assigned after payment).
`total`	`Money`	Total amount including taxes. A Money object with `value` (decimal string) and `currency` (ISO 4217 code).
`subtotal`	`Money`	Subtotal amount before taxes.
`taxSummary`	`array`	Tax breakdown by rate. Each item contains a `taxRate` object (`name`, `percentage`, `taxablePercentage`) and an `amount` Money object.
`lines`	`array`	Array of line items in this order. See OrderLine properties below.
`merchantDetails`	`BillingDetails`	Merchant billing details (seller). Includes `fullName`, `companyName`, `vatNumber`, `streetAndNumber`, `streetAdditional`, `city`, `region`, `postalCode`, `country`, and `email`.
`customerDetails`	`BillingDetails`	Customer billing details (buyer). Same structure as merchantDetails.
`createdAt`	`string`	When this order was created (ISO 8601 format).
`links`	`object`	HATEOAS links to related resources. Contains `self`, `customer`, and optionally `customerInvoice` links.

OrderLine Properties

Name	Type	Description
`id`	`string`	Unique identifier for this line item (starts with `order_item_`).
`resource`	`string`	The resource type. Always `orderline`.
`description`	`string`	Description of the item.
`quantity`	`integer`	Number of units.
`basePrice`	`Money`	Price per unit before taxes.
`total`	`Money`	Total price including taxes (basePrice x quantity + taxes).
`subtotal`	`Money`	Subtotal before taxes (basePrice x quantity).
`taxes`	`array`	Tax breakdown by rate for this line. Each item contains a `taxRate` object and an `amount` Money object.

List all orders

GET /v1/orders

This endpoint allows you to retrieve a paginated list of all your orders. By default, a maximum of ten orders are shown per page.

Optional parameters

Name	Type	Description
`limit`	`integer`	The number of orders to return (default: 10, max: 100).
`startingAfter`	`string`	A cursor for use in pagination. Returns results after this order ID.
`endingBefore`	`string`	A cursor for use in pagination. Returns results before this order ID.

curl -G https://api.vatly.com/v1/orders \
  -H "Authorization: Bearer live_your_api_key_here" \
  -d limit=10

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$orders = $vatly->orders->page();

{
  "data": [
    {
      "id": "order_Hn5xWqVfKm8RjTgYbUcP",
      "resource": "order",
      "merchantId": "merchant_Tk7mNvBxKw2RjTgYcZaE",
      "customerId": "customer_Xk9pQrSvWm4NjLhYbUcP",
      "testmode": false,
      "metadata": {},
      "paymentMethod": "ideal",
      "status": "paid",
      "invoiceNumber": "INV-2024-0001",
      "total": {
        "value": "35.09",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "29.00",
        "currency": "EUR"
      },
      "taxSummary": [
        {
          "taxRate": {
            "name": "VAT",
            "percentage": 21,
            "taxablePercentage": 100
          },
          "amount": {
            "value": "6.09",
            "currency": "EUR"
          }
        }
      ],
      "lines": [
        {
          "id": "order_item_Mn6xBtPvKw2RjTgYcZaE",
          "resource": "orderline",
          "description": "Pro Monthly Subscription",
          "quantity": 1,
          "basePrice": {
            "value": "29.00",
            "currency": "EUR"
          },
          "total": {
            "value": "35.09",
            "currency": "EUR"
          },
          "subtotal": {
            "value": "29.00",
            "currency": "EUR"
          },
          "taxes": [
            {
              "taxRate": {
                "name": "VAT",
                "percentage": 21,
                "taxablePercentage": 100
              },
              "amount": {
                "value": "6.09",
                "currency": "EUR"
              }
            }
          ]
        }
      ],
      "merchantDetails": {
        "fullName": "Vatly B.V.",
        "companyName": "Vatly",
        "vatNumber": "NL123456789B01",
        "streetAndNumber": "Keizersgracht 123",
        "streetAdditional": null,
        "city": "Amsterdam",
        "region": null,
        "postalCode": "1015 CJ",
        "country": "NL",
        "email": "billing@vatly.com"
      },
      "customerDetails": {
        "fullName": "John Doe",
        "companyName": "Acme Corp",
        "vatNumber": null,
        "streetAndNumber": "123 Main Street",
        "streetAdditional": null,
        "city": "Berlin",
        "region": null,
        "postalCode": "10115",
        "country": "DE",
        "email": "john@acme.com"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/orders/order_Hn5xWqVfKm8RjTgYbUcP",
          "type": "application/json"
        },
        "customer": {
          "href": "https://api.vatly.com/v1/customers/customer_Xk9pQrSvWm4NjLhYbUcP",
          "type": "application/json"
        }
      }
    }
  ],
  "count": 1,
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/orders",
      "type": "application/json"
    },
    "next": null,
    "prev": null
  }
}

Get an order

GET /v1/orders/:orderId

This endpoint allows you to retrieve a specific order by its ID.

Parameters

Name	Type	Description
`orderId`	`string`	The unique identifier of the order.

curl https://api.vatly.com/v1/orders/order_Hn5xWqVfKm8RjTgYbUcP \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$order = $vatly->orders->get('order_Hn5xWqVfKm8RjTgYbUcP');

{
  "id": "order_Hn5xWqVfKm8RjTgYbUcP",
  "resource": "order",
  "merchantId": "merchant_Tk7mNvBxKw2RjTgYcZaE",
  "customerId": "customer_Xk9pQrSvWm4NjLhYbUcP",
  "testmode": false,
  "metadata": {},
  "paymentMethod": "ideal",
  "status": "paid",
  "invoiceNumber": "INV-2024-0001",
  "total": {
    "value": "35.09",
    "currency": "EUR"
  },
  "subtotal": {
    "value": "29.00",
    "currency": "EUR"
  },
  "taxSummary": [
    {
      "taxRate": {
        "name": "VAT",
        "percentage": 21,
        "taxablePercentage": 100
      },
      "amount": {
        "value": "6.09",
        "currency": "EUR"
      }
    }
  ],
  "lines": [
    {
      "id": "order_item_Jk4pQrSvWm8NjLhYbUcP",
      "resource": "orderline",
      "description": "Pro Monthly Subscription",
      "quantity": 1,
      "basePrice": {
        "value": "29.00",
        "currency": "EUR"
      },
      "total": {
        "value": "35.09",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "29.00",
        "currency": "EUR"
      },
      "taxes": [
        {
          "taxRate": {
            "name": "VAT",
            "percentage": 21,
            "taxablePercentage": 100
          },
          "amount": {
            "value": "6.09",
            "currency": "EUR"
          }
        }
      ]
    }
  ],
  "merchantDetails": {
    "fullName": "Vatly B.V.",
    "companyName": "Vatly",
    "vatNumber": "NL123456789B01",
    "streetAndNumber": "Keizersgracht 123",
    "streetAdditional": null,
    "city": "Amsterdam",
    "region": null,
    "postalCode": "1015 CJ",
    "country": "NL",
    "email": "billing@vatly.com"
  },
  "customerDetails": {
    "fullName": "John Doe",
    "companyName": "Acme Corp",
    "vatNumber": null,
    "streetAndNumber": "123 Main Street",
    "streetAdditional": null,
    "city": "Berlin",
    "region": null,
    "postalCode": "10115",
    "country": "DE",
    "email": "john@acme.com"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/orders/order_Hn5xWqVfKm8RjTgYbUcP",
      "type": "application/json"
    },
    "customer": {
      "href": "https://api.vatly.com/v1/customers/customer_Xk9pQrSvWm4NjLhYbUcP",
      "type": "application/json"
    },
    "customerInvoice": {
      "href": "https://vatly.com/invoices/order_Hn5xWqVfKm8RjTgYbUcP",
      "type": "text/html"
    }
  }
}

Request address update link

POST /v1/orders/:orderId/request-address-update-link

This endpoint allows you to request a signed link that customers can use to update their order billing address. The link is valid for a limited time (typically 24 hours).

Parameters

Name	Type	Description
`orderId`	`string`	The unique identifier of the order.

curl -X POST https://api.vatly.com/v1/orders/order_Hn5xWqVfKm8RjTgYbUcP/request-address-update-link \
  -H "Authorization: Bearer live_your_api_key_here"

$vatly = new \Vatly\API\VatlyApiClient();
$vatly->setApiKey('live_your_api_key_here');

$link = $vatly->orders->requestAddressUpdateLink('order_Hn5xWqVfKm8RjTgYbUcP');

{
  "href": "https://vatly.com/invoices/order_Hn5xWqVfKm8RjTgYbUcP/edit?signature=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "type": "text/html"
}

Edit this pageorReport an issue

Subscription Plans

On this page, we'll dive into the different subscription plan endpoints you can use to query your plans programmatically.

Order Refunds

On this page, we'll dive into the different order refund endpoints you can use to manage refunds programmatically.