Sell by Link

Overview

Sell by Link exposes a POST contract to create the sale and the link, plus two auxiliary GET contracts — one to look up the sale state and another to discover a product's custom options. All requests and responses use application/json and require Authorization: Bearer {token}.

Endpoints

Summary of the available contracts. Base URL in the examples: /api2. Every call requires Authorization: Bearer {{token}}.

Authentication

Use the Yep REST API OAuth 2.0 flow to generate a token and send it on every call. See OAuth 2.0 for the full flow.

curl -X POST "{{route}}/api2/oauth/token" \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "client_id={{client_id}}" \
  -d "client_secret={{client_secret}}" \
  -d "grant_type=client_credentials"

Authorization: Bearer {{token}}
Accept: application/json
Content-Type: application/json

Create sale and link

Creates the sale and all items in a single operation, returning the checkout link. The total is calculated by the server.

curl -X POST "{{route}}/api2/vendalink" \
  -H "Authorization: Bearer {{token}}" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 6ec51e29-038d-4dbd-9be9-d6940935f103" \
  -d '{
    "email": "[email protected]",
    "store_id": 1,
    "coupon_code": "WELCOME10",
    "send_email": false,
    "expires_at": "2026-07-23T23:59:59-03:00",
    "items": [
      {
        "sku": "SKU-001",
        "qty": 2,
        "price": 149.90,
        "options": {
          "123": "456",
          "124": "Custom text",
          "125": "2026-07-20",
          "126": "14:30"
        }
      }
    ]
  }'

{
  "success": true,
  "vendalink": {
    "id": 87,
    "status": "pending",
    "email": "[email protected]",
    "store_id": 1,
    "coupon_code": "WELCOME10",
    "total": 299.80,
    "currency": "BRL",
    "checkout_url": "https://store.example.com/vendalink/venda/index/id/TOKEN",
    "expires_at": "2026-07-24T02:59:59+00:00",
    "order_increment_id": null,
    "email_sent": false,
    "created_at": "2026-07-16T19:30:00+00:00",
    "items": [
      {
        "id": 201,
        "sku": "SKU-001",
        "qty": 2,
        "price": 149.90,
        "row_total": 299.80,
        "options": {
          "123": "456",
          "124": "Custom text",
          "125": "2026-07-20",
          "126": "14:30"
        }
      }
    ]
  }
}

Idempotency

The Idempotency-Key ensures that resending the exact same request does not create a second sale. Generate a new key for each new sale and preserve the key when repeating the same operation.

Look up sale

Looks up the created sale. The response uses the same vendalink object returned on creation.

curl "{{route}}/api2/vendalink?id={{vendalink_id}}" \
  -H "Authorization: Bearer {{token}}" \
  -H "Accept: application/json"

Product options

Returns the identifiers and formats required to fill items[].options. Query this endpoint before sending products with custom options.

curl "{{route}}/api2/vendalink/options?sku={{product_sku}}&store_id={{store_id}}" \
  -H "Authorization: Bearer {{token}}" \
  -H "Accept: application/json"

{
  "success": true,
  "product": {
    "sku": "SKU-001",
    "name": "Sample product",
    "catalog_price": 159.90,
    "options": [
      {
        "option_id": 123,
        "title": "Color",
        "type": "drop_down",
        "required": true,
        "values": [
          {
            "option_type_id": 456,
            "title": "Blue",
            "price": 0,
            "price_type": "fixed"
          }
        ]
      }
    ]
  }
}

Option formats

The value of each key in items[].options depends on the option type returned above.

Integration recommendations

Consolidated best practices for integrations that create personalized sales with the Yep Platform.

Recommended

• Generate a new Idempotency-Key for each new sale and preserve the key when repeating the exact same operation.
• Query /api2/vendalink/options before sending products with custom options.
• Treat the checkout_url as sensitive data — do not publish it in open logs or shared channels.
• Let the server calculate the total; send only items[].price as each item's commercial price.
• Check email_sent and the warnings list in the response when using send_email=true.

Avoid

• Reusing the same Idempotency-Key with a different payload — it returns 409 Conflict.
• Sending a total field in the body — the total is always calculated by the server.
• Filling items[].options without first querying the product options endpoint.
• Using the catalog price as the sale value — the effective value is the items[].price sent.

Common errors

{
  "success": false,
  "error": "Objective error description.",
  "field": "items.0.options.123"
}