Create Order

POST

orders

Create Order

curl --request POST \
  --url https://api.vertracloud.app/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "plan": "<string>",
  "months": 123
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({plan: '<string>', months: 123})
};

fetch('https://api.vertracloud.app/v1/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vertracloud.app/v1/orders"

payload = {
    "plan": "<string>",
    "months": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/orders"

	payload := strings.NewReader("{\n  \"plan\": \"<string>\",\n  \"months\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "response": {
    "id": "order-abc123",
    "code": null,
    "status": "unpaid",
    "plan": "starter-1",
    "duration": 1,
    "discount": { "percent": null, "coupon": null, "price": 7.7 },
    "price": 7.7,
    "expires_at": "2026-09-22T12:00:00.000Z",
    "allowed_payment_methods": ["pix", "card"]
  }
}

string

default:"purchase"

What the order is for. Possible values: purchase, renew, upgrade.

string

required

The plan name being purchased, renewed or upgraded to, such as starter-1 or pro-4. The names are in List Plans. A plan that is no longer sold returns PLAN_NOT_FOR_SALE.

integer

required

How many months to purchase: 1, 3, 6 or 12. Any other value returns INVALID_MONTHS. A 3-month order gets 10% off, a 6-month order 15% off and a 12-month order 25% off the monthly price; price and discount already include it. Quote Order returns the exact amount before you create the order.

string

An optional discount coupon code.

The order needs complete billing details: check complete in Get Billing Details.

A renew order requires the target plan to match the account’s current plan; an upgrade order requires it to be strictly larger. Use type: "purchase" when there’s no active plan of that kind yet.

Response

object

Show Toggle object

string

The order ID.

string | null

The redeem code, when the order was created for a code-based flow; null otherwise.

string

Always unpaid right after creation.

string

The plan name.

integer

Duration in months.

object

Show Toggle object

number | null

Discount percentage applied, if any.

string | null

The coupon code applied, if any.

number

The price before the discount.

number

The final price, after the discount.

string | null

When the order (and its PIX charge, once generated) expires unpaid.

string[]

Payment methods the order accepts: pix and card. A coupon restricted to one method narrows the list.

{
  "response": {
    "id": "order-abc123",
    "code": null,
    "status": "unpaid",
    "plan": "starter-1",
    "duration": 1,
    "discount": { "percent": null, "coupon": null, "price": 7.7 },
    "price": 7.7,
    "expires_at": "2026-09-22T12:00:00.000Z",
    "allowed_payment_methods": ["pix", "card"]
  }
}

Error Responses

string

The error code indicating the reason for failure. Possible values:

AUTH_TOKEN_MISSING, API_KEY_INVALID, SESSION_REVOKED: The Authorization header is missing, the API key is invalid, or the dashboard session was revoked (401).
API_KEY_IP_DENIED, API_KEY_SCOPE_DENIED: The API key is used from an IP outside its allowlist, or it lacks the scope the route requires (403).
USER_NOT_FOUND: The authenticated user was not found.
INVALID_PAYLOAD: The request body failed validation.
BILLING_DETAILS_INCOMPLETE: The billing details are not complete (name, address and, in Brazil, CPF/CNPJ). Save them with Update Billing Details and try again.
MISSING_PLAN_OR_MONTHS: plan or months is missing.
INVALID_MONTHS: months is not 1, 3, 6 or 12.
INVALID_PLAN: The plan name does not exist.
PLAN_NOT_FOR_SALE: The plan is no longer sold (400).
NOT_AN_UPGRADE: For type: "upgrade", the target plan is not larger than the current one.
PLAN_MISMATCH_FOR_RENEWAL: For type: "renew", the target plan does not match the current one.
PENDING_ORDER_LIMIT_REACHED: Too many unpaid orders already open.
INTERNAL_SERVER_ERROR: An unexpected server error occurred.

{
  "code": "INVALID_PLAN"
}

Last modified on November 1, 2026

Create Order

curl --request POST \
  --url https://api.vertracloud.app/v1/orders \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "plan": "<string>",
  "months": 123
}
'

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({plan: '<string>', months: 123})
};

fetch('https://api.vertracloud.app/v1/orders', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.vertracloud.app/v1/orders"

payload = {
    "plan": "<string>",
    "months": 123
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.vertracloud.app/v1/orders"

	payload := strings.NewReader("{\n  \"plan\": \"<string>\",\n  \"months\": 123\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

{
  "response": {
    "id": "order-abc123",
    "code": null,
    "status": "unpaid",
    "plan": "starter-1",
    "duration": 1,
    "discount": { "percent": null, "coupon": null, "price": 7.7 },
    "price": 7.7,
    "expires_at": "2026-09-22T12:00:00.000Z",
    "allowed_payment_methods": ["pix", "card"]
  }
}

Overview

Endpoints

Response

Error Responses

​Response

​Error Responses

Response

Error Responses