Orders List Endpoints

Server

Endpoints for interacting with orders.

Get Orders

GET

https://sandbox-api.vignette.id

/public/orders

This endpoint allows you to obtain a list of all partner orders with all the necessary information about the order.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

Get Orders › query Parameters

status

string

Returns filtered orders by status.

• Statuses

Each vignette can have one of the statuses:

PENDING, WILL BE ACTIVE, ACTIVE, EXPIRED, REFUNDED, DELETED

More about status list.

bug_report

boolean

Use with all endpoints to inform us for bugs in API

Default: false

Get Orders › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Orders › Responses

Successful operation

AllOrdersObject

id

string

email

string

created_date

number

GET/public/orders

curl https://sandbox-api.vignette.id/public/orders \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "error": null,
  "pages": {
    "total": 1,
    "current": 1
  },
  "result": [
    {
      "id": "r24c1gqblg",
      "custom_id": "partner-custom-id",
      "product": "vignette-si-2a",
      "user_id": "y8efybzbk4",
      "cars": [
        {
          "plate": "AA2122AS",
          "country": "ua"
        }
      ],
      "purchase_date": 1756130793,
      "start_from": 1758232800,
      "start_date": 1758232800,
      "end_date": 1758837599,
      "period": "7",
      "type": "vignette",
      "country": "si",
      "status": "ACTIVE",
      "receipt": "https://vignette.id/invoices/pdf/199537_mxqu6g5b7v.pdf",
      "subaccount": "test_web"
    }
  ]
}

json

application/json

Create order

POST

https://sandbox-api.vignette.id

/public/orders

New paid order on partner side initiate request for processing in Vignette ID system.

⚠️ Once an order moves to the pending status, it can no longer be modified.

Create order › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Content-Type

string · enum · required

Specifies the format of the request body. Must be 'application/json' for requests with a JSON body.

Enum values:

application/json

Default: application/json

Create order › Request Body

terms_and_privacy_accepted

boolean · required

Must be true to indicate that terms and privacy are accepted. Partner need to store this information in the user order.

Example: true

order_has_been_paid

boolean · required

• true - this means that the partner accepted and processed the payment on his side.

• false - to pay for an order, the API generates a link and returns it to the response in payment_link, which the partner must display to the user. The payment is processed on our side.

Example: true

object[] · required

Array of Vehicles with vehicle plate and registration country.

object[] · required

Array of vignettes with custom id, name, period, and start date.

send_payment_link

string · enum

Not required. Defines how the payment link should be delivered to the user:

• email - send the payment link to the user's email.

• sms - send the payment link via SMS to the user's phone number.

If omitted, the payment link is only returned in the response (payment_link).

Enum values:

sms

Example: email

allowed_payment_providers

string[] · minItems: 1 · unique

Not required. Payment providers the user can pay with on the Vignette ID payment page. The final provider is chosen by the user at checkout.

If omitted, defaults to ["stripe", "paypal"].

⚠️ Only allowed when order_has_been_paid is false — the payment page is not shown when the partner collects the payment.

Enum values:

stripe

paypal

monobank

Default: ["stripe","paypal"]

open_order_details_by_default

boolean

Not required. When true, the Vignette ID payment page opens with the order details section expanded. Defaults to false.

⚠️ Only allowed when order_has_been_paid is false — the payment page is not shown when the partner collects the payment.

Example: false

Default: false

object

User data.

subaccount

string

Partner can provide different sub-account names which mean different user UI or apps

object

Create order › Responses

Successful operation

ResponseOrderObject

Error can be null, a simple string code, or an object with details.

object

POST/public/orders

curl https://sandbox-api.vignette.id/public/orders \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "terms_and_privacy_accepted": true,
  "order_has_been_paid": true,
  "user": {
    "email": "[email protected]"
  },
  "cars": [
    {
      "country": "ua",
      "plate": "AA2122AC"
    }
  ],
  "products": [
    {
      "custom_id": "partner-000001",
      "name": "vignette-si-2a",
      "start_date": 1758283731,
      "period": 7
    }
  ]
}'

Example Request Body

{
  "terms_and_privacy_accepted": true,
  "order_has_been_paid": true,
  "user": {
    "email": "[email protected]"
  },
  "cars": [
    {
      "country": "ua",
      "plate": "AA2122AC"
    }
  ],
  "products": [
    {
      "custom_id": "partner-000001",
      "name": "vignette-si-2a",
      "start_date": 1758283731,
      "period": 7
    }
  ]
}

json

application/json

Example Responses

{
  "error": null,
  "result": {
    "user_id": "j28ho77yuh",
    "orders": [
      {
        "id": "1k99i2ddy6",
        "custom_id": "partner-000001",
        "currency": "EUR",
        "profit": 2.55
      }
    ]
  },
  "payment_link": "https://vignette.id/pay/{environment}/{custom_id}"
}

json

application/json

Validate order

POST

https://sandbox-api.vignette.id

/public/orders/validate

Pre-flight validation of an order payload (vehicles + products) before calling Create order.

Returns the same 400 error types as Create order but performs no payment, no order persistence and no user creation. Use it to validate a basket on the partner side before checkout.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

Validate order › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Content-Type

string · enum · required

Specifies the format of the request body. Must be 'application/json' for requests with a JSON body.

Enum values:

application/json

Default: application/json

Validate order › Request Body

Pre-flight validation of an order payload (cars + products) before calling create order. Does not require payment, terms or user data.

object[] · required

Array of Vehicles with vehicle plate and registration country.

object[] · required

Array of vignettes with name, period, and start date.

Validate order › Responses

Payload is valid and an order with the same data would be accepted by Create order

ResponseValidatePlateObject

Error can be null, a simple string code, or an object with details.

object

POST/public/orders/validate

curl https://sandbox-api.vignette.id/public/orders/validate \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <token>' \
  --data '{
  "cars": [
    {
      "plate": "ABC123",
      "country": "at",
      "vin_code": "1HGBH41JXMN109186"
    }
  ],
  "products": [
    {
      "name": "vignette-si-2a",
      "start_date": 1758283731,
      "period": 7
    }
  ]
}'

Example Request Body

{
  "cars": [
    {
      "plate": "ABC123",
      "country": "at",
      "vin_code": "1HGBH41JXMN109186"
    }
  ],
  "products": [
    {
      "name": "vignette-si-2a",
      "start_date": 1758283731,
      "period": 7
    }
  ]
}

json

application/json

Example Responses

{
  "error": null,
  "result": {
    "valid": true
  }
}

json

application/json

Get Order

GET

https://sandbox-api.vignette.id

/public/orders/{id}

• id - order id in Vignette ID system

• custom_id - order id in Partner system

• provider_id - unique vignette id in national (government) providers systems

• cars -> provider_id - unique vignette identificator in national provider system

• cars -> pdf - confirmation file from national provider system.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

• modify, full_refund, partial_refund - capability blocks telling you whether the order can be modified or refunded right now, until when, and (for refunds) for how much. Present on Flex orders.

• flex - Flexible Service configuration recorded on the order.

Get Order › path Parameters

id

string · required

id of order in Vignette ID system or custom_id from Partner system

Get Order › query Parameters

bug_report

boolean

Use with all endpoints to inform us for bugs in API

Default: false

Get Order › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Order › Responses

Specific order description test

OrderObject

Error can be null, a simple string code, or an object with details.

object

GET/public/orders/{id}

curl https://sandbox-api.vignette.id/public/orders/:id \
  --header 'Authorization: Bearer <token>'

Example Responses

{
  "error": null,
  "result": {
    "id": "r24c1gqblg",
    "custom_id": "partner-custom-id",
    "product": "vignette-si-2a",
    "user_id": "y8efybzbk4",
    "cars": [
      {
        "plate": "AA2122AS",
        "country": "ua"
      }
    ],
    "purchase_date": 1756130793,
    "start_from": 1758232800,
    "start_date": 1758232800,
    "end_date": 1758837599,
    "period": "7",
    "type": "vignette",
    "country": "si",
    "vehicle_type": "car",
    "status": "PENDING",
    "modify": {
      "eligible": true,
      "available_at": null,
      "expires_at": 1758207600,
      "reason_code": "default_flex_window"
    },
    "full_refund": {
      "eligible": true,
      "available_at": null,
      "expires_at": 1758211200,
      "amount_eur": 15.45,
      "percent": 100,
      "reason_code": "more_than_6h_before_start"
    },
    "partial_refund": {
      "eligible": false,
      "available_at": 1758211200,
      "expires_at": 1758214800,
      "amount_eur": 7.73,
      "percent": 50,
      "reason_code": "full_refund_applies"
    },
    "flex": {
      "type": "default",
      "price": 3.29,
      "enabled": true,
      "original_price": 3.29,
      "is_partner_paid": false
    },
    "receipt": "https://vignette.id/invoices/pdf/199537_mxqu6g5b7v.pdf",
    "subaccount": "test_web"
  }
}

json

application/json

Get Order Status

GET

https://sandbox-api.vignette.id

/public/orders/{id}/status

Returns only the order status. Applicable in cases where you need to check only the status without other information.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

Get Order Status › path Parameters

id

string · required

id of order in Vignette ID system or custom_id from Partner system

Get Order Status › query Parameters

bug_report

boolean

Use with all endpoints to inform us for bugs in API

Default: false

Get Order Status › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Get Order Status › Responses

Specific order description test

OrderObject

Error can be null, a simple string code, or an object with details.

object

Cancel Pending Order

POST

https://sandbox-api.vignette.id

/public/orders/{id}/cancel-pending

The ability to cancel an order that has a PENDING status if it is not processed within the specified time period

• PENDING - only.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

Cancel Pending Order › path Parameters

id

string · required

id of order in Vignette ID system or custom_id from Partner system

Cancel Pending Order › query Parameters

bug_report

boolean

Use with all endpoints to inform us for bugs in API

Default: false

Cancel Pending Order › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Cancel Pending Order › Responses

Specific order description test

success-cancel-order-schema

error

object | string | null

object

Cancel Deferred Order

POST

https://sandbox-api.vignette.id

/public/orders/{id}/cancel-deferred

The ability to cancel an order that has a DEFERRED status if it is not processed within the specified time period

• DEFERRED - only.

⚠️ Rate limit policy applies to this endpoint Check Rate Limits

Cancel Deferred Order › path Parameters

id

string · required

id of order in Vignette ID system or custom_id from Partner system

Cancel Deferred Order › query Parameters

bug_report

boolean

Use with all endpoints to inform us for bugs in API

Default: false

Cancel Deferred Order › Headers

Authorization

string · required

The Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.

Cancel Deferred Order › Responses

Specific order description test

success-cancel-order-schema

error

object | string | null

object

Users List Endpoints External Orders Endpoints