Criar order bump

curl --request POST \
  --url https://apiv3.usecorvex.com.br/api/v1/order-bumps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Store-Id: <x-store-id>' \
  --data '
{
  "name": "Proteção extra",
  "description": null,
  "type": "PRODUCT",
  "status": "ACTIVE",
  "isStandalone": false,
  "productId": "22222222-2222-4222-8222-222222222222",
  "productVariantId": null,
  "discountType": "PERCENT",
  "discountAmount": 10,
  "title": "Leve também a proteção",
  "subtitle": null,
  "image": "https://cdn.example.com/bump.png",
  "price": 49.9,
  "discountedPrice": 39.9,
  "autoAdd": false,
  "required": false,
  "maxQuantity": 1,
  "startsAt": null,
  "endsAt": null,
  "triggerProductIds": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "targetCategoryIds": [],
  "minCartTotal": null,
  "maxCartTotal": null,
  "position": 1,
  "displayOrder": 1,
  "buttonText": "Adicionar"
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Store-Id': '<x-store-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Proteção extra',
    description: null,
    type: 'PRODUCT',
    status: 'ACTIVE',
    isStandalone: false,
    productId: '22222222-2222-4222-8222-222222222222',
    productVariantId: null,
    discountType: 'PERCENT',
    discountAmount: 10,
    title: 'Leve também a proteção',
    subtitle: null,
    image: 'https://cdn.example.com/bump.png',
    price: 49.9,
    discountedPrice: 39.9,
    autoAdd: false,
    required: false,
    maxQuantity: 1,
    startsAt: null,
    endsAt: null,
    triggerProductIds: ['22222222-2222-4222-8222-222222222222'],
    targetCategoryIds: [],
    minCartTotal: null,
    maxCartTotal: null,
    position: 1,
    displayOrder: 1,
    buttonText: 'Adicionar'
  })
};

fetch('https://apiv3.usecorvex.com.br/api/v1/order-bumps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://apiv3.usecorvex.com.br/api/v1/order-bumps"

payload = {
    "name": "Proteção extra",
    "description": None,
    "type": "PRODUCT",
    "status": "ACTIVE",
    "isStandalone": False,
    "productId": "22222222-2222-4222-8222-222222222222",
    "productVariantId": None,
    "discountType": "PERCENT",
    "discountAmount": 10,
    "title": "Leve também a proteção",
    "subtitle": None,
    "image": "https://cdn.example.com/bump.png",
    "price": 49.9,
    "discountedPrice": 39.9,
    "autoAdd": False,
    "required": False,
    "maxQuantity": 1,
    "startsAt": None,
    "endsAt": None,
    "triggerProductIds": ["22222222-2222-4222-8222-222222222222"],
    "targetCategoryIds": [],
    "minCartTotal": None,
    "maxCartTotal": None,
    "position": 1,
    "displayOrder": 1,
    "buttonText": "Adicionar"
}
headers = {
    "X-Store-Id": "<x-store-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "success": true,
  "data": {
    "orderBump": {
      "id": "66666666-6666-4666-8666-666666666666",
      "storeId": "11111111-1111-4111-8111-111111111111",
      "name": "Proteção extra",
      "description": null,
      "type": "PRODUCT",
      "status": "ACTIVE",
      "productId": "22222222-2222-4222-8222-222222222222",
      "productVariantId": null,
      "discountType": "PERCENT",
      "discountAmount": 10,
      "title": "Leve também a proteção",
      "subtitle": null,
      "image": "https://cdn.example.com/bump.png",
      "price": 49.9,
      "discountedPrice": 39.9,
      "autoAdd": false,
      "required": false,
      "maxQuantity": 1,
      "startsAt": null,
      "endsAt": null,
      "triggerProductIds": [
        "22222222-2222-4222-8222-222222222222"
      ],
      "targetCategoryIds": [],
      "minCartTotal": null,
      "maxCartTotal": null,
      "position": 1,
      "displayOrder": 1,
      "isStandalone": false,
      "standaloneSettings": null,
      "createdAt": "2026-09-24T14:00:00.000Z",
      "updatedAt": "2026-09-24T14:00:00.000Z",
      "buttonText": "Adicionar"
    }
  }
}

{
  "success": false,
  "error": {
    "message": "X-Store-Id deve ser um UUID válido",
    "code": "VALIDATION_ERROR"
  },
  "meta": {
    "timestamp": "2026-09-24T14:00:00.000Z",
    "status": 400
  }
}

{
  "success": false,
  "error": {
    "message": "Esta rota exige uma API Key. Use Authorization: Bearer cvx_live_...",
    "code": "AUTH_API_KEY_REQUIRED"
  },
  "meta": {
    "timestamp": "2026-09-24T14:00:00.000Z",
    "status": 401
  }
}

{
  "success": false,
  "error": {
    "message": "Sua API Key não tem o escopo necessário para esta operação.",
    "code": "AUTH_SCOPE_DENIED"
  },
  "meta": {
    "timestamp": "2026-09-24T14:00:00.000Z",
    "status": 403
  }
}

{
  "success": false,
  "message": "Muitas requisições. Tente novamente em instantes.",
  "error": "RATE_LIMITED",
  "retryAfter": 12
}

Order bumps

Criar order bump

Há dois modos, definidos por isStandalone.

Produto da loja (isStandalone: false): envie productId e title. É o caso mais comum.

Avulso (isStandalone: true): envie standaloneSettings com title, price e image. Não envie productId.

maxQuantity limita quantas unidades deste item o cliente pode adicionar. Quantidade de itens no carrinho (minCartQuantity / maxCartQuantity) existe só em brindes, não aqui. Para valor do carrinho use minCartTotal / maxCartTotal.

POST

api

order-bumps

Criar order bump

curl --request POST \
  --url https://apiv3.usecorvex.com.br/api/v1/order-bumps \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Store-Id: <x-store-id>' \
  --data '
{
  "name": "Proteção extra",
  "description": null,
  "type": "PRODUCT",
  "status": "ACTIVE",
  "isStandalone": false,
  "productId": "22222222-2222-4222-8222-222222222222",
  "productVariantId": null,
  "discountType": "PERCENT",
  "discountAmount": 10,
  "title": "Leve também a proteção",
  "subtitle": null,
  "image": "https://cdn.example.com/bump.png",
  "price": 49.9,
  "discountedPrice": 39.9,
  "autoAdd": false,
  "required": false,
  "maxQuantity": 1,
  "startsAt": null,
  "endsAt": null,
  "triggerProductIds": [
    "22222222-2222-4222-8222-222222222222"
  ],
  "targetCategoryIds": [],
  "minCartTotal": null,
  "maxCartTotal": null,
  "position": 1,
  "displayOrder": 1,
  "buttonText": "Adicionar"
}
'

const options = {
  method: 'POST',
  headers: {
    'X-Store-Id': '<x-store-id>',
    Authorization: 'Bearer <token>',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    name: 'Proteção extra',
    description: null,
    type: 'PRODUCT',
    status: 'ACTIVE',
    isStandalone: false,
    productId: '22222222-2222-4222-8222-222222222222',
    productVariantId: null,
    discountType: 'PERCENT',
    discountAmount: 10,
    title: 'Leve também a proteção',
    subtitle: null,
    image: 'https://cdn.example.com/bump.png',
    price: 49.9,
    discountedPrice: 39.9,
    autoAdd: false,
    required: false,
    maxQuantity: 1,
    startsAt: null,
    endsAt: null,
    triggerProductIds: ['22222222-2222-4222-8222-222222222222'],
    targetCategoryIds: [],
    minCartTotal: null,
    maxCartTotal: null,
    position: 1,
    displayOrder: 1,
    buttonText: 'Adicionar'
  })
};

fetch('https://apiv3.usecorvex.com.br/api/v1/order-bumps', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://apiv3.usecorvex.com.br/api/v1/order-bumps"

payload = {
    "name": "Proteção extra",
    "description": None,
    "type": "PRODUCT",
    "status": "ACTIVE",
    "isStandalone": False,
    "productId": "22222222-2222-4222-8222-222222222222",
    "productVariantId": None,
    "discountType": "PERCENT",
    "discountAmount": 10,
    "title": "Leve também a proteção",
    "subtitle": None,
    "image": "https://cdn.example.com/bump.png",
    "price": 49.9,
    "discountedPrice": 39.9,
    "autoAdd": False,
    "required": False,
    "maxQuantity": 1,
    "startsAt": None,
    "endsAt": None,
    "triggerProductIds": ["22222222-2222-4222-8222-222222222222"],
    "targetCategoryIds": [],
    "minCartTotal": None,
    "maxCartTotal": None,
    "position": 1,
    "displayOrder": 1,
    "buttonText": "Adicionar"
}
headers = {
    "X-Store-Id": "<x-store-id>",
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "success": true,
  "data": {
    "orderBump": {
      "id": "66666666-6666-4666-8666-666666666666",
      "storeId": "11111111-1111-4111-8111-111111111111",
      "name": "Proteção extra",
      "description": null,
      "type": "PRODUCT",
      "status": "ACTIVE",
      "productId": "22222222-2222-4222-8222-222222222222",
      "productVariantId": null,
      "discountType": "PERCENT",
      "discountAmount": 10,
      "title": "Leve também a proteção",
      "subtitle": null,
      "image": "https://cdn.example.com/bump.png",
      "price": 49.9,
      "discountedPrice": 39.9,
      "autoAdd": false,
      "required": false,
      "maxQuantity": 1,
      "startsAt": null,
      "endsAt": null,
      "triggerProductIds": [
        "22222222-2222-4222-8222-222222222222"
      ],
      "targetCategoryIds": [],
      "minCartTotal": null,
      "maxCartTotal": null,
      "position": 1,
      "displayOrder": 1,
      "isStandalone": false,
      "standaloneSettings": null,
      "createdAt": "2026-09-24T14:00:00.000Z",
      "updatedAt": "2026-09-24T14:00:00.000Z",
      "buttonText": "Adicionar"
    }
  }
}

{
  "success": false,
  "error": {
    "message": "X-Store-Id deve ser um UUID válido",
    "code": "VALIDATION_ERROR"
  },
  "meta": {
    "timestamp": "2026-09-24T14:00:00.000Z",
    "status": 400
  }
}

{
  "success": false,
  "error": {
    "message": "Esta rota exige uma API Key. Use Authorization: Bearer cvx_live_...",
    "code": "AUTH_API_KEY_REQUIRED"
  },
  "meta": {
    "timestamp": "2026-09-24T14:00:00.000Z",
    "status": 401
  }
}

{
  "success": false,
  "error": {
    "message": "Sua API Key não tem o escopo necessário para esta operação.",
    "code": "AUTH_SCOPE_DENIED"
  },
  "meta": {
    "timestamp": "2026-09-24T14:00:00.000Z",
    "status": 403
  }
}

{
  "success": false,
  "message": "Muitas requisições. Tente novamente em instantes.",
  "error": "RATE_LIMITED",
  "retryAfter": 12
}

Authorizations

Authorization

string

header

required

API Key no formato cvx_live_..., criada no painel Corvex. Não use JWT de sessão nem x-api-key.

Headers

X-Store-Id

string<uuid>

required

UUID da loja. A chave precisa ter esta loja autorizada.

Body

application/json

name

string

required

Required string length: 3 - 100

type

enum<string>

required

Available options:

PRODUCT,

DISCOUNT,

SHIPPING_UPGRADE,

WARRANTY

isStandalone

boolean

required

false = oferta de um produto da loja. true = oferta avulsa, sem produto do catálogo.

description

string | null

status

enum<string>

Available options:

ACTIVE,

INACTIVE,

SCHEDULED

productId

string<uuid>

Obrigatório se isStandalone é false. Não envie se isStandalone é true.

productVariantId

string<uuid> | null

discountType

enum<string> | null

Available options:

CURRENCY,

PERCENT

discountAmount

number | null

title

string

Texto do card no checkout. Obrigatório se isStandalone é false. No modo avulso pode omitir: usa standaloneSettings.title.

subtitle

string | null

image

string<uri> | null

price

number | null

discountedPrice

number | null

autoAdd

boolean

required

boolean

maxQuantity

integer | null

Quantidade máxima deste item no bump (o produto oferecido). Não é quantidade de itens no carrinho — isso existe só em brindes (minCartQuantity / maxCartQuantity).

startsAt

string<date-time> | null

endsAt

string<date-time> | null

triggerProductIds

string[]

Produtos no carrinho que disparam o bump. Array vazio = qualquer produto.

targetCategoryIds

string[]

Coleções que disparam o bump. Array vazio = sem filtro por coleção.

minCartTotal

number | null

Valor mínimo do carrinho para exibir o bump. null = sem mínimo.

Required range: x >= 0

maxCartTotal

number | null

Valor máximo do carrinho para exibir o bump. null = sem máximo.

Required range: x >= 0

position

integer

Required range: x >= 1

displayOrder

integer

Required range: x >= 1

buttonText

string | null

Maximum string length: 50

standaloneSettings

object

Obrigatório se isStandalone é true. Envie title, price e image. Não combine com productId.

Show child attributes

Response

Criado.

Visão geral

Fundamentos

Checkout externo

Catálogo

Pedidos e entrega

Clientes

Marketing

Webhooks

Automações

Criar order bump

Authorizations

Headers

Body

Response