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 `ord_`).
`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 `pending`, `paid`, or `failed`.
`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`	`Money`	Total tax amount.
`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` and `customer` links.

OrderLine Properties

Name	Type	Description
`id`	`string`	Unique identifier for this line item (starts with `oli_`).
`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`	`Money`	Tax amount for this line.

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": "ord_abc123def456",
      "resource": "order",
      "merchantId": "mer_abc123",
      "customerId": "cus_xyz789",
      "testmode": false,
      "metadata": null,
      "paymentMethod": "ideal",
      "status": "paid",
      "invoiceNumber": "INV-2024-0001",
      "total": {
        "value": "120.99",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "100.00",
        "currency": "EUR"
      },
      "taxSummary": {
        "value": "20.99",
        "currency": "EUR"
      },
      "lines": [
        {
          "id": "oli_abc123",
          "resource": "orderline",
          "description": "Pro Monthly Subscription",
          "quantity": 1,
          "basePrice": {
            "value": "100.00",
            "currency": "EUR"
          },
          "total": {
            "value": "120.99",
            "currency": "EUR"
          },
          "subtotal": {
            "value": "100.00",
            "currency": "EUR"
          },
          "taxes": {
            "value": "20.99",
            "currency": "EUR"
          }
        }
      ],
      "merchantDetails": {
        "fullName": null,
        "companyName": "Acme Corp",
        "vatNumber": "NL123456789B01",
        "streetAndNumber": "123 Business Ave",
        "streetAdditional": null,
        "city": "Amsterdam",
        "region": "North Holland",
        "postalCode": "1012 AB",
        "country": "NL",
        "email": "billing@acme.com"
      },
      "customerDetails": {
        "fullName": "John Doe",
        "companyName": null,
        "vatNumber": null,
        "streetAndNumber": "456 Customer St",
        "streetAdditional": "Apt 789",
        "city": "Rotterdam",
        "region": "South Holland",
        "postalCode": "3012 CD",
        "country": "NL",
        "email": "john@example.com"
      },
      "createdAt": "2024-01-15T10:30:00Z",
      "links": {
        "self": {
          "href": "https://api.vatly.com/v1/orders/ord_abc123def456",
          "type": "application/json"
        },
        "customer": {
          "href": "https://api.vatly.com/v1/customers/cus_xyz789",
          "type": "application/json"
        }
      }
    }
  ],
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/orders?limit=10",
      "type": "application/json"
    },
    "next": {
      "href": "https://api.vatly.com/v1/orders?startingAfter=ord_abc123def456&limit=10",
      "type": "application/json"
    },
    "prev": null
  },
  "count": 1
}

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/ord_abc123def456 \
  -H "Authorization: Bearer live_your_api_key_here"

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

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

{
  "id": "ord_abc123def456",
  "resource": "order",
  "merchantId": "mer_abc123",
  "customerId": "cus_xyz789",
  "testmode": false,
  "metadata": null,
  "paymentMethod": "ideal",
  "status": "paid",
  "invoiceNumber": "INV-2024-0001",
  "total": {
    "value": "120.99",
    "currency": "EUR"
  },
  "subtotal": {
    "value": "100.00",
    "currency": "EUR"
  },
  "taxSummary": {
    "value": "20.99",
    "currency": "EUR"
  },
  "lines": [
    {
      "id": "oli_abc123",
      "resource": "orderline",
      "description": "Pro Monthly Subscription",
      "quantity": 1,
      "basePrice": {
        "value": "100.00",
        "currency": "EUR"
      },
      "total": {
        "value": "120.99",
        "currency": "EUR"
      },
      "subtotal": {
        "value": "100.00",
        "currency": "EUR"
      },
      "taxes": {
        "value": "20.99",
        "currency": "EUR"
      }
    }
  ],
  "merchantDetails": {
    "fullName": null,
    "companyName": "Acme Corp",
    "vatNumber": "NL123456789B01",
    "streetAndNumber": "123 Business Ave",
    "streetAdditional": null,
    "city": "Amsterdam",
    "region": "North Holland",
    "postalCode": "1012 AB",
    "country": "NL",
    "email": "billing@acme.com"
  },
  "customerDetails": {
    "fullName": "John Doe",
    "companyName": null,
    "vatNumber": null,
    "streetAndNumber": "456 Customer St",
    "streetAdditional": "Apt 789",
    "city": "Rotterdam",
    "region": "South Holland",
    "postalCode": "3012 CD",
    "country": "NL",
    "email": "john@example.com"
  },
  "createdAt": "2024-01-15T10:30:00Z",
  "links": {
    "self": {
      "href": "https://api.vatly.com/v1/orders/ord_abc123def456",
      "type": "application/json"
    },
    "customer": {
      "href": "https://api.vatly.com/v1/customers/cus_xyz789",
      "type": "application/json"
    }
  }
}

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/ord_abc123def456/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('ord_abc123def456');

{
  "href": "https://vatly.com/invoices/ord_abc123def456/edit?signature=abc123...",
  "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.