Skip to main content

Overview

Payment Links are shareable checkout URLs that enable you to sell products without building a custom payment experience. Simply create a link, share it with customers, and start accepting cryptocurrency payments.

A Payment Link is a hosted checkout page that:

  • 🔗 Provides a shareable URL for instant checkout
  • 🛍️ Displays product details, variants, and pricing
  • 💳 Handles payment processing automatically
  • 📱 Works across all devices (mobile, tablet, desktop)
  • 🔄 Supports both one-time and subscription payments

URL Format:

https://buy.martianpay.com/{payment_link_id}

Example:

https://buy.martianpay.com/7LIqrRHEO492styzYHuRzXGg

Key Features​

FeatureDescription
No Coding RequiredShare links via email, social media, or messaging apps
Product VariantsSupport size, color, and other product options
Addon ProductsOptional extras with quantity controls
Subscription BillingRecurring payments with selling plans
Hosted CheckoutComplete payment experience on MartianPay domain
Automatic PricingPrice ranges calculated from variants
Mobile OptimizedResponsive design for all screen sizes

Use Cases​

Perfect For:

  • 🏪 E-commerce: Sell products directly via social media
  • 📧 Email Marketing: Include payment links in campaigns
  • 💼 Invoicing: Send payment requests to clients
  • 🎫 Event Tickets: Quick checkout for events
  • 📱 Social Selling: Share on Instagram, Twitter, WhatsApp
  • 🌐 No Website Needed: Start selling without a website
FeaturePayment LinkPayment Intent
IntegrationNo code neededAPI integration required
Checkout UIHosted by MartianPayBuild your own
Best ForQuick setup, social sellingCustom payment flows
URL Sharing✅ Yes❌ No
Product Display✅ Built-in❌ You build it
Setup TimeMinutesHours/Days

💡 Quick Start: Need to start selling immediately? Payment Links are your fastest option. For custom checkout experiences, see Payment Intent APIs.

How Payment Links Work

Component Overview​

1. Product Association​

Each payment link connects to a single product that includes:

  • Product images and media
  • Description and details
  • Multiple variants (size, color, etc.)
  • Pricing information (one-time or subscription)

2. Variant Types​

Primary Variants:

  • Main product options (e.g., Small, Medium, Large)
  • Customer selects one option
  • Each variant can have different pricing

Addon Variants:

  • Optional extras or accessories
  • Customer can select multiple with quantity controls
  • Add-on pricing added to base price

Default Variant:

  • Pre-selected option when link opens
  • Guides customers to recommended choice

3. Pricing Display​

  • Price Ranges: Automatically calculated from variant prices
  • One-Time Payments: Single charge at checkout
  • Subscription Plans: Recurring billing with optional discounts
  • Transparent Pricing: All costs shown before payment

API Reference

  1. Subscription Integration:
    • Products with requires_selling_plan: true become subscription-only
    • Selling plans define billing frequency and discounts
    • Trial periods supported for subscription products
    • Pricing tiers for different billing cycles

Payment links are built on top of the Products API:

  1. Create Product: First create a product with options and variants (see Product APIs)
  2. Define Variants: Set up primary variants (main selections) and optional addon variants
  3. Create Payment Link: Select which variants to include in the link
  4. Share URL: Distribute the payment link URL to customers
  5. Customer Checkout: Customers select options and complete payment
  6. Payment Intent Created: System automatically creates payment intent upon checkout

Primary Variants vs Add-on Variants​

Primary Variants:

  • Represent the main product selection
  • Customer must choose one primary variant
  • Examples: T-shirt sizes (Small, Medium, Large), subscription tiers (Basic, Pro, Enterprise)
  • Used in price range calculation
  • Displayed as the main product options

Add-on Variants:

  • Optional extras or accessories
  • Customer can select multiple add-ons
  • Support quantity constraints (min_quantity, max_quantity)
  • Examples: Gift wrapping, extended warranty, extra accessories
  • Added to cart alongside primary variant selection
  • Increase total price when selected

Integration with Subscriptions via Selling Plans​

Payment links support subscription products through selling plans:

  1. Selling Plan Groups: Collections of subscription options (e.g., "Subscribe & Save")
  2. Selling Plans: Individual plans with billing policies (monthly, yearly, etc.)
  3. Pricing Policies: Define discounts and pricing tiers across billing cycles
  4. Trial Periods: Optional free or discounted trial before regular billing

When a customer completes a payment link checkout for a subscription product:

  • Payment intent is created with the selected selling plan
  • Upon successful payment, subscription is automatically created
  • Recurring billing follows the selling plan's schedule
  • Customer can manage subscription through Subscription APIs

Ephemeral Tokens for Third-Party Authentication​

Payment links support seamless customer authentication through ephemeral tokens, allowing you to integrate with external identity providers (IDP) without requiring customers to log in again.

Use Case: When you have an existing user account system (e.g., Instagram, WhatsApp, your own platform), you can generate an ephemeral token to authenticate the customer automatically when they access the payment link.

How It Works:

  1. Generate Ephemeral Token: Your backend calls the Create Ephemeral Token API with the customer's identifier
  2. Append Token to URL: Add the token as a query parameter to the payment link URL
  3. Customer Access: When customer clicks the link, they're automatically authenticated
  4. Seamless Checkout: No additional login required - customer proceeds directly to checkout

API Endpoint: POST /v1/customers/ephemeral_tokens

Request Example:

curl --location --request POST 'https://api.martianpay.com/v1/customers/ephemeral_tokens' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data '{
  "allow_create": true,
  "channel_metadata": {
    "instagram_user_id": "12345",
    "dm_thread_id": "67890"
  },
  "idp_key": "email",
  "idp_subject": "user@example.com",
  "issued_by": "instagram_commerce_bot",
  "provider": "instagram",
  "order_id": "order_123"
}'

Response:

{
  "expires_at": 1735689600,
  "token": "eph_abc123xyz789"
}

Payment Link URL with Token:

https://buy.martianpay.com/{payment_link_id}?ephemeral_token=eph_abc123xyz789

Key Parameters:

  • idp_key: (Optional) Identity provider type ("email", "phone", or "uuid"). If not provided, creates an anonymous ephemeral token
  • idp_subject: (Optional) Customer identifier (email address, phone number, or UUID). If not provided along with idp_key, creates an anonymous ephemeral token
  • provider: (Optional) Platform name (e.g., "instagram", "whatsapp", "wechat"). If not provided, creates an anonymous ephemeral token
  • order_id: (Optional) Order identifier to associate with this ephemeral token. When provided, this order_id will be returned when the token is resolved. Useful for tracking which order the customer authentication is for
  • return_url: (Optional) URL to redirect the customer after authentication/payment. Used in social media integrations where the flow needs to return to a specific page (e.g., "https://example.com/payment/success")
  • allow_create: (Optional) Auto-create customer if not found (default: true)
  • channel_metadata: (Optional) Platform-specific data for tracking
  • issued_by: (Optional) System or service issuing the token (for audit logging)

Token Characteristics:

  • Short-lived: Typically expires in 5-15 minutes
  • Single-use: Intended for immediate use
  • Secure: Cannot be reused after expiration
  • Auto-creates customers: If allow_create: true, new customers are created automatically

Benefits:

  • Seamless UX: Customers don't need to log in again
  • Multi-platform: Works with any external authentication system
  • Secure: Time-limited tokens reduce security risks
  • Flexible: Supports email and phone-based identification

Workflow​

  1. Create products with variants and optional selling plans
  2. Create payment link selecting primary and optional addon variants
  3. Share the payment link URL with customers
  4. Customers select options and complete payment through hosted page
  5. System creates payment intent and processes payment
  6. For subscription products, subscription is created automatically
  7. Manage active/inactive status of payment links as needed
  8. Delete inactive payment links when no longer needed

Creates a hosted payment link with product variants. Payment links provide a shareable URL where customers can complete purchases with customizable product options.

For detailed API reference, see: Create Payment Link API

Request Parameters:

  • product_id (required): ID of the product to sell
  • default_variant_id (required): Default variant to display when link is opened
  • primary_variant_ids (required): Array of variant IDs available as primary selections
  • addon_variants (optional): Array of addon variant configurations with quantity constraints
  • variant_config (optional): UI and default selection metadata for customization

Request Example (Simple Payment Link):

curl --location --request POST 'https://api.martianpay.com/v1/payment_links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data-raw '{
  "product_id": "prod_abc123",
  "default_variant_id": "var_def456",
  "primary_variant_ids": ["var_def456", "var_ghi789", "var_jkl012"]
}'

Request Example (Payment Link with Variants and Add-ons):

curl --location --request POST 'https://api.martianpay.com/v1/payment_links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data-raw '{
  "product_id": "prod_abc123",
  "default_variant_id": "var_def456",
  "primary_variant_ids": ["var_def456", "var_ghi789", "var_jkl012"],
  "addon_variants": [
    {
      "variant_id": "var_addon_001",
      "min_quantity": 0,
      "max_quantity": 5
    },
    {
      "variant_id": "var_addon_002",
      "min_quantity": 1,
      "max_quantity": 3
    }
  ],
  "variant_config": {
    "display_mode": "grid",
    "show_inventory": true
  }
}'

Request Example (Payment Link with Subscription - Selling Plans):

curl --location --request POST 'https://api.martianpay.com/v1/payment_links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data-raw '{
  "product_id": "prod_subscription_box",
  "default_variant_id": "var_monthly_standard",
  "primary_variant_ids": [
    "var_monthly_standard",
    "var_quarterly_standard",
    "var_yearly_standard"
  ]
}'

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "plink_xyz789abc",
    "active": true,
    "created_at": 1701234567,
    "updated_at": 1701234567,
    "url": "https://pay.martianpay.com/link/plink_xyz789abc",
    "variant_config": {
      "display_mode": "grid",
      "show_inventory": true
    },
    "product": {
      "id": "prod_abc123",
      "name": "Premium T-Shirt",
      "description": "High-quality cotton t-shirt in multiple sizes and colors",
      "active": true,
      "default_currency": "USD",
      "created_at": 1701234000,
      "updated_at": 1701234000,
      "version": 1,
      "collect_shipping_address": true,
      "collect_tax_address": true,
      "tax_code": "txcd_99999999",
      "requires_selling_plan": false,
      "selling_plan_group_ids": [],
      "metadata": {
        "category": "apparel",
        "brand": "Premium Basics"
      },
      "price": {
        "amount": 29.99,
        "asset_id": "USD"
      },
      "media_order": ["media_001", "media_002"],
      "options": [
        {
          "name": "Size",
          "sort_order": 1,
          "values": [
            {
              "value": "Small",
              "sort_order": 1
            },
            {
              "value": "Medium",
              "sort_order": 2
            },
            {
              "value": "Large",
              "sort_order": 3
            }
          ]
        },
        {
          "name": "Color",
          "sort_order": 2,
          "values": [
            {
              "value": "Black",
              "sort_order": 1,
              "swatch": {
                "type": "color",
                "value": "#000000"
              }
            },
            {
              "value": "White",
              "sort_order": 2,
              "swatch": {
                "type": "color",
                "value": "#FFFFFF"
              }
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "var_def456",
          "active": true,
          "version": 1,
          "inventory_quantity": 100,
          "option_values": {
            "Size": "Small",
            "Color": "Black"
          },
          "price": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "media_order": ["media_001"],
          "selling_plan_group_ids": []
        },
        {
          "id": "var_ghi789",
          "active": true,
          "version": 1,
          "inventory_quantity": 150,
          "option_values": {
            "Size": "Medium",
            "Color": "Black"
          },
          "price": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "media_order": ["media_001"],
          "selling_plan_group_ids": []
        },
        {
          "id": "var_jkl012",
          "active": true,
          "version": 1,
          "inventory_quantity": 75,
          "option_values": {
            "Size": "Large",
            "Color": "White"
          },
          "price": {
            "amount": 32.99,
            "asset_id": "USD"
          },
          "media_order": ["media_002"],
          "selling_plan_group_ids": []
        }
      ],
      "includes": {
        "media": [
          {
            "id": "media_001",
            "url": "https://cdn.example.com/tshirt-black.jpg",
            "content_type": "image/jpeg",
            "alt_text": "Premium T-Shirt Black",
            "width": 1200,
            "height": 1600
          },
          {
            "id": "media_002",
            "url": "https://cdn.example.com/tshirt-white.jpg",
            "content_type": "image/jpeg",
            "alt_text": "Premium T-Shirt White",
            "width": 1200,
            "height": 1600
          }
        ]
      },
      "selling_plan_groups": []
    },
    "primary_variants": [
      {
        "variant_id": "var_def456",
        "is_primary": true,
        "quantity": 1,
        "min_quantity": null,
        "max_quantity": null,
        "variant": {
          "id": "var_def456",
          "active": true,
          "inventory_quantity": 100,
          "option_values": {
            "Size": "Small",
            "Color": "Black"
          },
          "price": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "media_order": ["media_001"],
          "selling_plan_group_ids": [],
          "selling_plan_groups": [],
          "selling_plan_pricing": [],
          "version": 1
        }
      },
      {
        "variant_id": "var_ghi789",
        "is_primary": true,
        "quantity": 1,
        "min_quantity": null,
        "max_quantity": null,
        "variant": {
          "id": "var_ghi789",
          "active": true,
          "inventory_quantity": 150,
          "option_values": {
            "Size": "Medium",
            "Color": "Black"
          },
          "price": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "media_order": ["media_001"],
          "selling_plan_group_ids": [],
          "selling_plan_groups": [],
          "selling_plan_pricing": [],
          "version": 1
        }
      },
      {
        "variant_id": "var_jkl012",
        "is_primary": true,
        "quantity": 1,
        "min_quantity": null,
        "max_quantity": null,
        "variant": {
          "id": "var_jkl012",
          "active": true,
          "inventory_quantity": 75,
          "option_values": {
            "Size": "Large",
            "Color": "White"
          },
          "price": {
            "amount": 32.99,
            "asset_id": "USD"
          },
          "media_order": ["media_002"],
          "selling_plan_group_ids": [],
          "selling_plan_groups": [],
          "selling_plan_pricing": [],
          "version": 1
        }
      }
    ],
    "addon_variants": [
      {
        "variant_id": "var_addon_001",
        "is_primary": false,
        "quantity": 0,
        "min_quantity": 0,
        "max_quantity": 5,
        "variant": {
          "id": "var_addon_001",
          "active": true,
          "inventory_quantity": 500,
          "option_values": {
            "Type": "Gift Wrapping"
          },
          "price": {
            "amount": 5.99,
            "asset_id": "USD"
          },
          "media_order": [],
          "selling_plan_group_ids": [],
          "selling_plan_groups": [],
          "selling_plan_pricing": [],
          "version": 1
        }
      }
    ],
    "price_range": {
      "min": {
        "amount": 29.99,
        "asset_id": "USD"
      },
      "max": {
        "amount": 32.99,
        "asset_id": "USD"
      }
    },
    "includes": {
      "media": [
        {
          "id": "media_001",
          "url": "https://cdn.example.com/tshirt-black.jpg",
          "content_type": "image/jpeg",
          "alt_text": "Premium T-Shirt Black",
          "width": 1200,
          "height": 1600
        },
        {
          "id": "media_002",
          "url": "https://cdn.example.com/tshirt-white.jpg",
          "content_type": "image/jpeg",
          "alt_text": "Premium T-Shirt White",
          "width": 1200,
          "height": 1600
        }
      ]
    }
  }
}

Important Notes:

  1. Required Fields:

    • product_id: Must reference an existing active product
    • default_variant_id: Must be included in primary_variant_ids
    • primary_variant_ids: Must contain at least one variant from the product

  2. Primary Variants:

    • These are the main product options customers can choose
    • System automatically calculates price range from primary variants
    • Displayed as the primary selection interface
    • Each primary variant has is_primary: true

  3. Addon Variants:

    • Optional additional items customers can add to their order
    • Support quantity constraints with min_quantity and max_quantity
    • Set min_quantity: 0 to make add-on truly optional
    • Set min_quantity: 1 to require at least one (e.g., mandatory accessories)
    • max_quantity limits how many can be added

  4. Price Range:

    • Automatically calculated from primary variants
    • Shows minimum and maximum prices across all primary variants
    • Useful for displaying price ranges in marketing materials
    • Does not include addon variant prices

  5. Payment Link URL:

    • Unique hosted checkout URL returned in url field
    • Format: https://pay.martianpay.com/link/{payment_link_id}
    • Share this URL with customers via any channel
    • URL remains active as long as payment link is active

  6. Variant Configuration: Cannot be modified after creation. To change variants, create a new payment link and deactivate the old one.

  7. Product Snapshots: The response includes complete product information for display, including media assets and variant details.

Understanding the Response​

How to Check if the Request Was Successful:

FieldValueMeaning
error_code"success"✅ Payment link created successfully
error_code"invalid_request_error"❌ Invalid configuration or missing required fields
error_codeOther value❌ Other error occurred

Key Fields:

FieldDescription
idUnique payment link identifier
urlHosted checkout URL to share with customers
activeWhether payment link accepts payments (true/false)
primary_variant_idDefault variant customers will see
product_idAssociated product ID
created_atCreation timestamp

Payment Link URL:

  • Format: https://pay.martianpay.com/link/{payment_link_id}
  • Share via email, SMS, social media, QR code, etc.
  • Remains active as long as active: true
  • Customers can complete purchase directly on this URL

Next Steps:

  • Save the payment link id for future updates
  • Share the url with customers
  • Test the payment link to verify configuration
  • Monitor orders via Orders API
  • Deactivate when no longer needed

Retrieves a paginated list of payment links for your merchant account. Supports filtering by active status and product ID.

For detailed API reference, see: List Payment Links API

Request:

curl --location --request GET 'https://api.martianpay.com/v1/payment_links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data-raw '{
  "page": 0,
  "page_size": 10,
  "active": true
}'

Request with Product Filter:

curl --location --request GET 'https://api.martianpay.com/v1/payment_links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data-raw '{
  "page": 0,
  "page_size": 20,
  "active": true,
  "product": "prod_abc123"
}'

Request Body Parameters:

  • page (optional): Page number, zero-based (minimum: 0)
  • page_size (required): Items per page (minimum: 1, maximum: 50)
  • active (optional): Filter by active status (true=active, false=inactive)
  • product (optional): Filter by product ID to find all links containing this product

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "page": 0,
    "page_size": 10,
    "total": 25,
    "payment_links": [
      {
        "id": "plink_xyz789abc",
        "active": true,
        "created_at": 1701234567,
        "updated_at": 1701234567,
        "url": "https://pay.martianpay.com/link/plink_xyz789abc",
        "variant_config": {},
        "product": {
          "id": "prod_abc123",
          "name": "Premium T-Shirt",
          "description": "High-quality cotton t-shirt",
          "active": true,
          "default_currency": "USD",
          "created_at": 1701234000,
          "updated_at": 1701234000,
          "version": 1,
          "collect_shipping_address": true,
          "collect_tax_address": true,
          "requires_selling_plan": false,
          "metadata": {},
          "price": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "media_order": ["media_001"],
          "options": [],
          "variants": [],
          "includes": {
            "media": [
              {
                "id": "media_001",
                "url": "https://cdn.example.com/tshirt.jpg",
                "content_type": "image/jpeg",
                "alt_text": "Premium T-Shirt",
                "width": 1200,
                "height": 1600
              }
            ]
          },
          "selling_plan_groups": []
        },
        "primary_variants": [
          {
            "variant_id": "var_def456",
            "is_primary": true,
            "quantity": 1,
            "variant": {
              "id": "var_def456",
              "active": true,
              "price": {
                "amount": 29.99,
                "asset_id": "USD"
              }
            }
          }
        ],
        "addon_variants": [],
        "price_range": {
          "min": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "max": {
            "amount": 32.99,
            "asset_id": "USD"
          }
        },
        "includes": {
          "media": [
            {
              "id": "media_001",
              "url": "https://cdn.example.com/tshirt.jpg",
              "content_type": "image/jpeg",
              "alt_text": "Premium T-Shirt",
              "width": 1200,
              "height": 1600
            }
          ]
        }
      }
    ]
  }
}

Important Notes:

  1. Pagination:

    • page_size is required (1-50)
    • Use page to navigate through results
    • total shows total number of payment links matching the filter

  2. Filtering:

    • Filter by active: true to show only active payment links
    • Filter by active: false to show inactive/deactivated links
    • Filter by product to find all payment links for a specific product
    • Combine filters to narrow results (e.g., active links for a product)

  3. Use Cases:

    • List all active payment links for display in admin dashboard
    • Find all payment links for a product before deleting the product
    • Identify inactive links that can be deleted
    • Audit payment link usage across products

  4. Product Information: Each payment link includes the associated product with media assets for easy display.

  5. Price Range: Automatically calculated and included for each payment link.

Understanding the Response​

Success Check: error_code: "success" ✅

Key Fields:

  • payment_links: Array of payment link objects
  • total: Total count matching filter
  • page, page_size: Pagination info

Filtering: Use active and product_id parameters to narrow results.

Next Steps: Use payment link id for details or updates, share url with customers.

Retrieves comprehensive information about a specific payment link, including product details, variants, pricing, and media assets.

For detailed API reference, see: Get Payment Link API

Request:

curl --location --request GET 'https://api.martianpay.com/v1/payment_links/plink_xyz789abc' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "plink_xyz789abc",
    "active": true,
    "created_at": 1701234567,
    "updated_at": 1701234567,
    "url": "https://pay.martianpay.com/link/plink_xyz789abc",
    "variant_config": {
      "display_mode": "grid",
      "show_inventory": true
    },
    "product": {
      "id": "prod_abc123",
      "name": "Premium T-Shirt",
      "description": "High-quality cotton t-shirt in multiple sizes and colors",
      "active": true,
      "default_currency": "USD",
      "created_at": 1701234000,
      "updated_at": 1701234000,
      "version": 1,
      "collect_shipping_address": true,
      "collect_tax_address": true,
      "tax_code": "txcd_99999999",
      "requires_selling_plan": false,
      "selling_plan_group_ids": [],
      "metadata": {
        "category": "apparel",
        "brand": "Premium Basics"
      },
      "price": {
        "amount": 29.99,
        "asset_id": "USD"
      },
      "media_order": ["media_001", "media_002"],
      "options": [
        {
          "name": "Size",
          "sort_order": 1,
          "values": [
            {
              "value": "Small",
              "sort_order": 1
            },
            {
              "value": "Medium",
              "sort_order": 2
            },
            {
              "value": "Large",
              "sort_order": 3
            }
          ]
        }
      ],
      "variants": [
        {
          "id": "var_def456",
          "active": true,
          "version": 1,
          "inventory_quantity": 100,
          "option_values": {
            "Size": "Small"
          },
          "price": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "media_order": ["media_001"],
          "selling_plan_group_ids": []
        }
      ],
      "includes": {
        "media": [
          {
            "id": "media_001",
            "url": "https://cdn.example.com/tshirt-front.jpg",
            "content_type": "image/jpeg",
            "alt_text": "Premium T-Shirt Front View",
            "width": 1200,
            "height": 1600
          },
          {
            "id": "media_002",
            "url": "https://cdn.example.com/tshirt-back.jpg",
            "content_type": "image/jpeg",
            "alt_text": "Premium T-Shirt Back View",
            "width": 1200,
            "height": 1600
          }
        ]
      },
      "selling_plan_groups": []
    },
    "primary_variants": [
      {
        "variant_id": "var_def456",
        "is_primary": true,
        "quantity": 1,
        "min_quantity": null,
        "max_quantity": null,
        "variant": {
          "id": "var_def456",
          "active": true,
          "inventory_quantity": 100,
          "option_values": {
            "Size": "Small"
          },
          "price": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "media_order": ["media_001"],
          "selling_plan_group_ids": [],
          "selling_plan_groups": [],
          "selling_plan_pricing": [],
          "version": 1
        }
      }
    ],
    "addon_variants": [],
    "price_range": {
      "min": {
        "amount": 29.99,
        "asset_id": "USD"
      },
      "max": {
        "amount": 32.99,
        "asset_id": "USD"
      }
    },
    "includes": {
      "media": [
        {
          "id": "media_001",
          "url": "https://cdn.example.com/tshirt-front.jpg",
          "content_type": "image/jpeg",
          "alt_text": "Premium T-Shirt Front View",
          "width": 1200,
          "height": 1600
        },
        {
          "id": "media_002",
          "url": "https://cdn.example.com/tshirt-back.jpg",
          "content_type": "image/jpeg",
          "alt_text": "Premium T-Shirt Back View",
          "width": 1200,
          "height": 1600
        }
      ]
    }
  }
}

Important Notes:

  1. Complete Details: The response includes:

    • Full product information with all variants
    • Media assets with URLs and metadata
    • Primary and addon variant configurations
    • Calculated price range
    • Selling plan information for subscription products

  2. Payment Link URL: Use the url field to share the payment link with customers.

  3. Variant Details: Each variant includes complete information:

    • Inventory quantity
    • Option values (e.g., Size: Small)
    • Pricing
    • Associated media assets
    • Selling plan associations for subscriptions

  4. Media Assets: Images are returned in the includes.media array, ordered according to the product's media_order.

  5. Authorization: Only returns payment links owned by the authenticated merchant.

Understanding the Response​

Success Check: error_code: "success" ✅ | "payment_link_not_found" ❌

Key Info: Complete payment link details including product, variants, media, pricing, and url for sharing.

Next Steps: Share url with customers, check active status, view product details.

Updates a payment link's active status. Payment link variant configuration cannot be modified after creation.

For detailed API reference, see: Update Payment Link API

Request (Activate Payment Link):

curl --location --request POST 'https://api.martianpay.com/v1/payment_links/plink_xyz789abc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data-raw '{
  "active": true
}'

Request (Deactivate Payment Link):

curl --location --request POST 'https://api.martianpay.com/v1/payment_links/plink_xyz789abc' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data-raw '{
  "active": false
}'

Request Body Parameters:

  • active (required): Set to true to activate or false to deactivate

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "plink_xyz789abc",
    "active": false,
    "created_at": 1701234567,
    "updated_at": 1701345678,
    "url": "https://pay.martianpay.com/link/plink_xyz789abc",
    "variant_config": {},
    "product": {
      "id": "prod_abc123",
      "name": "Premium T-Shirt",
      "description": "High-quality cotton t-shirt",
      "active": true,
      "default_currency": "USD",
      "price": {
        "amount": 29.99,
        "asset_id": "USD"
      }
    },
    "primary_variants": [
      {
        "variant_id": "var_def456",
        "is_primary": true,
        "quantity": 1,
        "variant": {
          "id": "var_def456",
          "active": true,
          "price": {
            "amount": 29.99,
            "asset_id": "USD"
          }
        }
      }
    ],
    "addon_variants": [],
    "price_range": {
      "min": {
        "amount": 29.99,
        "asset_id": "USD"
      },
      "max": {
        "amount": 32.99,
        "asset_id": "USD"
      }
    }
  }
}

Important Notes:

  1. Active Status Only: This endpoint only updates the active field. You cannot modify variant configuration, product association, or any other payment link settings.

  2. Deactivating Payment Links:

    • Set active: false to deactivate a payment link
    • Deactivated links cannot be accessed by customers
    • URL becomes inactive but is not deleted
    • Useful for temporarily disabling a link or retiring old campaigns

  3. Activating Payment Links:

    • Set active: true to reactivate a deactivated payment link
    • URL becomes accessible again with same configuration
    • Useful for seasonal promotions or limited-time offers

  4. Cannot Modify Variants: To change which variants are included in a payment link:

    • Create a new payment link with the desired configuration
    • Deactivate the old payment link
    • Update any references to use the new payment link URL

  5. Updated Timestamp: The updated_at field is updated when active status changes.

Error Responses:

{
  "code": 400,
  "error_code": "invalid_request_error",
  "msg": "Invalid parameters"
}
{
  "code": 404,
  "error_code": "resource_not_found",
  "msg": "Payment link not found"
}

Understanding the Response​

Success Check: error_code: "success" ✅ Payment link updated

What You Can Update:

  • ✅ active status (true/false)
  • ❌ Cannot change variants/product/pricing

Common Use: Set active: false to deactivate, active: true to reactivate.

Next Steps: Verify status change, test payment link URL if reactivated.

Permanently deletes an inactive payment link and all associated product mappings. Only inactive payment links can be deleted.

For detailed API reference, see: Delete Payment Link API

Request:

curl --location --request DELETE 'https://api.martianpay.com/v1/payment_links/plink_xyz789abc' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "deleted": true,
    "id": "plink_xyz789abc"
  }
}

Important Notes:

  1. Inactive Links Only: You can only delete payment links that have active: false. Set a payment link to inactive first, then delete it.

  2. Permanent Deletion: This operation permanently deletes the payment link and cannot be undone. The payment link URL will no longer work.

  3. Breaking Active Links: Deleting a payment link breaks the URL for any customers who may have bookmarked or saved it. Ensure the link is truly no longer needed before deletion.

  4. Cleanup: Use deletion to remove payment links that are:

    • No longer needed (e.g., expired campaigns)
    • Created for testing purposes
    • Superseded by new payment links

  5. Historical References: Payment intents created through the deleted payment link remain intact and retain their payment link details for record-keeping.

Error Responses:

{
  "code": 400,
  "error_code": "invalid_request_error",
  "msg": "Cannot delete active payment link. Set active=false first."
}
{
  "code": 404,
  "error_code": "resource_not_found",
  "msg": "Payment link not found"
}

Understanding the Response​

Success Check: error_code: "success" ✅ | deleted: true

Requirements: Payment link must be inactive (active: false) before deletion.

What Happens: Payment link permanently deleted, URL no longer works, historical data retained.

Next Steps: Confirm deletion via List API, update any references to this payment link.

Payment links support subscription products through selling plans, enabling recurring revenue without building a custom subscription checkout.

Understanding Selling Plans​

Selling Plan Groups are collections of subscription options:

  • Example: "Subscribe & Save" group with Monthly, Quarterly, and Yearly plans
  • Associated with products or specific variants
  • Can include multiple selling plans with different billing frequencies

Selling Plans define the subscription terms:

  • Billing frequency (monthly, quarterly, yearly, etc.)
  • Pricing policies with discounts
  • Trial periods
  • Validity dates

  1. Create Product with Selling Plans:

    • First create or update a product to include selling plan groups
    • Set requires_selling_plan: true for subscription-only products
    • Set requires_selling_plan: false to offer both one-time and subscription options

  2. Associate Selling Plans:

    • Product-level: selling_plan_group_ids at product level applies to all variants
    • Variant-level: selling_plan_group_ids at variant level overrides product-level plans

  3. Create Payment Link:

    • Create payment link with variants that have selling plans
    • Customers will see subscription options at checkout
    • Selling plan pricing automatically displayed with discounts

Example Request:

curl --location --request POST 'https://api.martianpay.com/v1/payment_links' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}' \
--data-raw '{
  "product_id": "prod_subscription_box",
  "default_variant_id": "var_monthly",
  "primary_variant_ids": [
    "var_monthly",
    "var_quarterly",
    "var_yearly"
  ]
}'

Example Response with Selling Plans:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "id": "plink_sub_123",
    "active": true,
    "created_at": 1701234567,
    "updated_at": 1701234567,
    "url": "https://pay.martianpay.com/link/plink_sub_123",
    "product": {
      "id": "prod_subscription_box",
      "name": "Premium Monthly Box",
      "description": "Curated monthly subscription box",
      "requires_selling_plan": true,
      "selling_plan_group_ids": ["spg_001"],
      "selling_plan_groups": [
        {
          "id": "spg_001",
          "name": "Subscribe & Save",
          "description": "Save up to 20% with longer commitments",
          "status": "active",
          "options": ["Billing Frequency"],
          "selling_plans": [
            {
              "id": "sp_monthly_001",
              "name": "Monthly",
              "description": "Billed monthly",
              "status": "active",
              "billing_policy_type": "RECURRING",
              "trial_period_days": "7",
              "version": 1
            },
            {
              "id": "sp_quarterly_001",
              "name": "Quarterly",
              "description": "Billed every 3 months, save 10%",
              "status": "active",
              "billing_policy_type": "RECURRING",
              "trial_period_days": "7",
              "version": 1
            },
            {
              "id": "sp_yearly_001",
              "name": "Yearly",
              "description": "Billed annually, save 20%",
              "status": "active",
              "billing_policy_type": "RECURRING",
              "trial_period_days": "14",
              "version": 1
            }
          ]
        }
      ]
    },
    "primary_variants": [
      {
        "variant_id": "var_monthly",
        "is_primary": true,
        "quantity": 1,
        "variant": {
          "id": "var_monthly",
          "active": true,
          "option_values": {
            "Frequency": "Monthly"
          },
          "price": {
            "amount": 49.99,
            "asset_id": "USD"
          },
          "selling_plan_pricing": [
            {
              "selling_plan_id": "sp_monthly_001",
              "selling_plan_name": "Monthly",
              "billing_cycle": "month",
              "currency": "USD",
              "trial_period_days": 7,
              "pricing_tiers": [
                {
                  "policy_type": "FIXED",
                  "after_cycle": 1,
                  "cycle_description": "First month",
                  "total_cycles": 1,
                  "base_price": "49.99",
                  "selling_plan_discount": "10.00",
                  "subtotal_before_policy": "49.99",
                  "subtotal_after_policy": "39.99"
                },
                {
                  "policy_type": "RECURRING",
                  "after_cycle": 2,
                  "cycle_description": "Month 2 onwards",
                  "total_cycles": 0,
                  "base_price": "49.99",
                  "selling_plan_discount": "0.00",
                  "subtotal_before_policy": "49.99",
                  "subtotal_after_policy": "49.99"
                }
              ]
            }
          ]
        }
      },
      {
        "variant_id": "var_yearly",
        "is_primary": true,
        "quantity": 1,
        "variant": {
          "id": "var_yearly",
          "active": true,
          "option_values": {
            "Frequency": "Yearly"
          },
          "price": {
            "amount": 479.88,
            "asset_id": "USD"
          },
          "selling_plan_pricing": [
            {
              "selling_plan_id": "sp_yearly_001",
              "selling_plan_name": "Yearly",
              "billing_cycle": "year",
              "currency": "USD",
              "trial_period_days": 14,
              "pricing_tiers": [
                {
                  "policy_type": "RECURRING",
                  "after_cycle": 1,
                  "cycle_description": "Every year",
                  "total_cycles": 0,
                  "base_price": "479.88",
                  "selling_plan_discount": "95.88",
                  "subtotal_before_policy": "479.88",
                  "subtotal_after_policy": "384.00"
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Subscription Creation Flow​

When a customer completes checkout on a payment link with subscription products:

  1. Customer Selects Options:

    • Chooses product variant (e.g., Monthly, Quarterly, Yearly)
    • System automatically displays associated selling plan(s)
    • Shows trial period if configured
    • Displays pricing tiers with discounts

  2. Payment Intent Created:

    • Payment intent is created with selected variant and selling plan
    • Includes selling_plan_id in line items
    • Customer completes payment

  3. Subscription Activated:

    • Upon successful payment, subscription is automatically created
    • Subscription status set to active
    • First billing cycle begins (after trial period if configured)
    • Customer receives confirmation

  4. Recurring Billing:

    • System automatically generates invoices based on billing cycle
    • Charges payment method on file
    • Applies pricing tiers based on cycle number
    • Continues until subscription is canceled or paused

Pricing Tiers​

Selling plans support complex pricing scenarios with pricing tiers:

FIXED Pricing Policy:

  • Applies to specific cycle(s)
  • Example: "$10 off first month"
  • Used for introductory offers
  • total_cycles defines how many cycles it applies to

RECURRING Pricing Policy:

  • Applies to ongoing cycles
  • Example: "10% off every month after first month"
  • after_cycle defines when it starts
  • total_cycles: 0 means it applies indefinitely

Example Pricing Tier Structure:

{
  "pricing_tiers": [
    {
      "policy_type": "FIXED",
      "after_cycle": 1,
      "cycle_description": "First month",
      "total_cycles": 1,
      "base_price": "49.99",
      "selling_plan_discount": "10.00",
      "subtotal_after_policy": "39.99"
    },
    {
      "policy_type": "RECURRING",
      "after_cycle": 2,
      "cycle_description": "Month 2 onwards",
      "total_cycles": 0,
      "base_price": "49.99",
      "selling_plan_discount": "5.00",
      "subtotal_after_policy": "44.99"
    }
  ]
}

This creates:

  • Cycle 1: $39.99 (20% off)
  • Cycle 2+: $44.99 (10% off ongoing)

Trial Periods​

Configure trial periods in selling plans:

  • trial_period_days defines trial length (e.g., 7, 14, 30 days)
  • Customer not charged during trial
  • Trial ends and first charge occurs after trial period
  • Different plans can have different trial lengths

Example:

  • Monthly plan: 7-day trial
  • Yearly plan: 14-day trial (longer commitment = longer trial)

Subscription-Only vs Optional Subscriptions​

Subscription-Only (requires_selling_plan: true):

  • Customer MUST select a subscription plan
  • No one-time purchase option
  • Useful for membership-based products

Optional Subscription (requires_selling_plan: false):

  • Customer can choose one-time purchase OR subscription
  • Checkout displays both options
  • Subscription option shows discounted pricing
  • Useful for products that work both ways (e.g., "Buy once or subscribe and save")

Managing Active Subscriptions​

Once subscriptions are created through payment links, manage them via the Subscription APIs:

  • List subscriptions: GET /subscriptions
  • Get subscription details: GET /subscriptions/{id}
  • Pause subscription: POST /subscriptions/{id}/pause
  • Resume subscription: POST /subscriptions/{id}/resume
  • Cancel subscription: POST /subscriptions/{id}/cancel

See Subscription APIs for complete subscription management documentation.

Best Practices​

  1. Payment Link Organization:

    • Use descriptive product names that clearly identify what customers are purchasing
    • Create separate payment links for different campaigns or channels
    • Track payment link performance by using metadata or unique product IDs
    • Deactivate old payment links instead of deleting to preserve historical data

  2. Variant Configuration:

    • Keep primary variants focused on main product choices (size, color, plan)
    • Use addon variants for optional extras (gift wrap, accessories)
    • Set sensible quantity limits on addon variants
    • Test payment link checkout flow before sharing with customers

  3. Pricing Strategy:

    • Use price range to market products effectively ("Starting at $29.99")
    • Consider addon variant pricing when marketing total value
    • For subscriptions, clearly show savings vs. one-time purchase
    • Display trial periods prominently in product descriptions

  4. Media Assets:

    • Upload high-quality product images for better conversion
    • Order images logically using media_order (front view first, then details)
    • Include variant-specific images when options affect appearance
    • Use descriptive alt_text for accessibility

  5. Subscription Products:

    • Clearly communicate subscription terms in product descriptions
    • Use trial periods to reduce purchase friction
    • Show pricing tiers transparently (e.g., "First month $39.99, then $44.99/month")
    • Consider offering multiple billing frequencies (monthly, yearly) for flexibility
    • Use requires_selling_plan: true only when appropriate

  6. Active Status Management:

    • Deactivate payment links when campaigns end rather than deleting
    • Keep seasonal payment links inactive between seasons
    • Regularly audit active payment links to ensure they're current
    • Delete only when payment link is truly obsolete

  7. URL Sharing:

    • Share payment link URLs via multiple channels (email, social media, SMS)
    • Use URL shorteners with tracking for marketing campaigns
    • Include payment links in QR codes for physical marketing materials
    • Test payment link accessibility before launching campaigns

  8. Product Updates:

    • If product details change significantly, create new payment link
    • Update product information (name, description, images) via Product API
    • Variant changes require new payment links (cannot modify existing)
    • Communicate changes to customers if payment link behavior changes

  9. Customer Experience:

    • Set collect_shipping_address: true for physical products
    • Configure appropriate tax codes for accurate tax calculation
    • Provide clear product descriptions with all relevant details
    • Test checkout flow from customer perspective

  10. Filtering and Search:

    • Use product filter to find all payment links for a product before deletion
    • Filter by active: true for customer-facing payment link lists
    • Filter by active: false to identify cleanup candidates
    • Implement pagination for large payment link collections

  11. Error Handling:

    • Validate product and variant IDs before creating payment links
    • Handle 404 errors gracefully (product or payment link not found)
    • Check product is active before creating payment link
    • Verify variant IDs belong to the specified product

  12. Testing:

    • Test payment links in both live and test mode
    • Verify all variant combinations work correctly
    • Test addon variant quantity constraints
    • Complete test purchases to verify full checkout flow
    • For subscriptions, verify correct selling plan is applied

7. Orders Management​

When customers complete payments through payment links, orders are automatically created to track their purchases. Orders provide a comprehensive record of each transaction, including customer information, shipping details, purchased items with quantities and pricing, and the current order status. This allows you to manage fulfillment, track order history, and provide customer support.

Orders contain all the essential information needed for order processing:

  • Customer Details: Name, email, phone number, and customer ID
  • Shipping Information: Full shipping address for physical product delivery
  • Order Items: Complete details of purchased products including variants, quantities, and prices
  • Payment Information: Payment method used and total amount
  • Order Status: Current state of the order (Pending, Paid, Shipping, Refunded, Canceled)
  • Timestamps: Order creation and last update times

7.1. List Orders​

Retrieves a paginated list of payment link orders for your merchant account. Supports searching by order number, customer name, or email, and filtering by order status.

For detailed API reference, see: List Orders API

Request:

curl --location --request GET 'https://api.martianpay.com/v1/orders?page=1&page_size=10' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Request with Search and Filter:

curl --location --request GET 'https://api.martianpay.com/v1/orders?search=john@example.com&status=Paid&page=1&page_size=20' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Query Parameters:

ParameterTypeRequiredDescription
searchstringNoSearch by order number, customer name, or email
statusstringNoFilter by status: Pending, Paid, Shipping, Refunded, Canceled
pageintegerNoPage number (default: 1)
page_sizeintegerNoItems per page (default: 10, max: 100)

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "orders": [
      {
        "order_number": "ORD-2025-01047",
        "external_id": "ext_c40wb",
        "created_at": 1701234567,
        "updated_at": 1701234567,
        "status": "Paid",
        "payment_method": "Crypto",
        "total_amount": {
          "amount": 159.97,
          "asset_id": "USD"
        },
        "customer": {
          "id": "cust_abc123",
          "name": "John Smith",
          "email": "john@example.com",
          "phone": "+1234567890"
        },
        "shipping_address": {
          "name": "John Smith",
          "line1": "123 Main Street",
          "line2": "Apt 4B",
          "city": "San Francisco",
          "state": "CA",
          "postal_code": "94102",
          "country": "US",
          "phone": "+1234567890"
        },
        "tax_region": {
          "country": "US",
          "state": "CA"
        },
        "items": [
          {
            "product": {
              "id": "prod_abc123",
              "name": "Premium T-Shirt",
              "description": "High-quality cotton t-shirt",
              "default_currency": "USD"
            },
            "option_values": {
              "Size": "Medium",
              "Color": "Black"
            },
            "quantity": 2,
            "unit_price": {
              "amount": 29.99,
              "asset_id": "USD"
            },
            "total": {
              "amount": 59.98,
              "asset_id": "USD"
            },
            "media_order": ["media_001"]
          },
          {
            "product": {
              "id": "prod_xyz789",
              "name": "Canvas Tote Bag",
              "description": "Eco-friendly canvas bag",
              "default_currency": "USD"
            },
            "option_values": {
              "Color": "Natural"
            },
            "quantity": 1,
            "unit_price": {
              "amount": 19.99,
              "asset_id": "USD"
            },
            "total": {
              "amount": 19.99,
              "asset_id": "USD"
            },
            "media_order": ["media_002"]
          }
        ]
      },
      {
        "order_number": "ORD-2025-01046",
        "external_id": "ext_d51xc",
        "created_at": 1701230000,
        "updated_at": 1701235000,
        "status": "Shipping",
        "payment_method": "Stripe",
        "total_amount": {
          "amount": 49.99,
          "asset_id": "USD"
        },
        "customer": {
          "id": "cust_def456",
          "name": "Jane Doe",
          "email": "jane@example.com",
          "phone": "+1987654321"
        },
        "shipping_address": {
          "name": "Jane Doe",
          "line1": "456 Oak Avenue",
          "city": "Austin",
          "state": "TX",
          "postal_code": "78701",
          "country": "US",
          "phone": "+1987654321"
        },
        "tax_region": {
          "country": "US",
          "state": "TX"
        },
        "items": [
          {
            "product": {
              "id": "prod_abc123",
              "name": "Premium T-Shirt",
              "description": "High-quality cotton t-shirt",
              "default_currency": "USD"
            },
            "option_values": {
              "Size": "Large",
              "Color": "White"
            },
            "quantity": 1,
            "unit_price": {
              "amount": 49.99,
              "asset_id": "USD"
            },
            "total": {
              "amount": 49.99,
              "asset_id": "USD"
            },
            "media_order": ["media_003"]
          }
        ]
      }
    ],
    "page": 1,
    "page_size": 10,
    "total": 47
  }
}

Important Notes:

  1. Search Functionality:

    • Use search parameter to find orders by order number, customer name, or email
    • Search is case-insensitive and performs partial matching
    • Example: search=john will match "John Smith", "john@example.com", "Johnson"
    • Useful for customer support queries and order lookups

  2. Status Filtering:

    • Filter orders by status to manage different stages of fulfillment
    • Pending: Order created but payment not yet completed
    • Paid: Payment successfully processed, ready for fulfillment
    • Shipping: Order has been shipped to customer
    • Refunded: Payment has been refunded to customer
    • Canceled: Order was canceled before or after payment

  3. Pagination:

    • Use page and page_size to navigate through large order lists
    • Maximum page_size is 100 items per page
    • total field shows total number of orders matching your filters
    • Default page size is 10 if not specified

  4. Order Items:

    • Each order contains an array of items with product details
    • Items include variant option values (size, color, etc.)
    • Quantity and pricing information for each item
    • total is calculated as quantity * unit_price

  5. Use Cases:

    • Display orders dashboard with filtering and search
    • Process orders by status (e.g., fetch all "Paid" orders for fulfillment)
    • Customer order history lookup by email
    • Generate reports and analytics on order volumes

7.2. Get Order Details​

Retrieves full details of a specific order including customer information, shipping address, and all order items.

For detailed API reference, see: Get Order Details API

Request:

curl --location --request GET 'https://api.martianpay.com/v1/orders/ORD-2025-01047' \
--header 'Authorization: Basic {BASE64_ENCODE(api_key + ":")}'

Response:

{
  "error_code": "success",
  "msg": "success",
  "data": {
    "order": {
      "order_number": "ORD-2025-01047",
      "external_id": "ext_c40wb",
      "created_at": 1701234567,
      "updated_at": 1701234567,
      "status": "Paid",
      "payment_method": "Crypto",
      "total_amount": {
        "amount": 159.97,
        "asset_id": "USD"
      },
      "customer": {
        "id": "cust_abc123",
        "name": "John Smith",
        "email": "john@example.com",
        "phone": "+1234567890"
      },
      "shipping_address": {
        "name": "John Smith",
        "line1": "123 Main Street",
        "line2": "Apt 4B",
        "city": "San Francisco",
        "state": "CA",
        "postal_code": "94102",
        "country": "US",
        "phone": "+1234567890"
      },
      "tax_region": {
        "country": "US",
        "state": "CA"
      },
      "items": [
        {
          "product": {
            "id": "prod_abc123",
            "name": "Premium T-Shirt",
            "description": "High-quality cotton t-shirt in multiple sizes and colors",
            "active": true,
            "default_currency": "USD",
            "collect_shipping_address": true,
            "collect_tax_address": true,
            "created_at": 1701230000,
            "updated_at": 1701230000,
            "version": 1,
            "metadata": {
              "category": "apparel",
              "brand": "Premium Basics"
            }
          },
          "option_values": {
            "Size": "Medium",
            "Color": "Black"
          },
          "quantity": 2,
          "unit_price": {
            "amount": 29.99,
            "asset_id": "USD"
          },
          "total": {
            "amount": 59.98,
            "asset_id": "USD"
          },
          "media_order": ["media_001"]
        },
        {
          "product": {
            "id": "prod_xyz789",
            "name": "Canvas Tote Bag",
            "description": "Eco-friendly canvas bag with custom printing",
            "active": true,
            "default_currency": "USD",
            "collect_shipping_address": true,
            "collect_tax_address": true,
            "created_at": 1701220000,
            "updated_at": 1701220000,
            "version": 1,
            "metadata": {
              "category": "accessories",
              "material": "canvas"
            }
          },
          "option_values": {
            "Color": "Natural"
          },
          "quantity": 1,
          "unit_price": {
            "amount": 19.99,
            "asset_id": "USD"
          },
          "total": {
            "amount": 19.99,
            "asset_id": "USD"
          },
          "media_order": ["media_002"]
        }
      ]
    }
  }
}

Important Notes:

  1. Order Number Format:

    • Order numbers follow the pattern: ORD-YYYY-NNNNN (e.g., ORD-2025-01047)
    • Use the exact order number in the URL path
    • Order number is unique across your merchant account

  2. Complete Order Information:

    • Full customer details including ID, name, email, and phone
    • Complete shipping address for order fulfillment
    • Tax region information for tax calculation records
    • Payment method used (Crypto, Paypal, Stripe)
    • Total amount including all items and applicable taxes

  3. Order Items Details:

    • Each item includes complete product information
    • Variant selections shown in option_values (e.g., Size, Color)
    • Individual item pricing: unit_price and total (quantity × unit_price)
    • Product metadata for additional context (category, brand, etc.)
    • Media asset references for displaying product images

  4. Order Status:

    • Pending: Order created, awaiting payment completion
    • Paid: Payment successful, order ready for processing
    • Shipping: Order has been dispatched to customer
    • Refunded: Full or partial refund issued
    • Canceled: Order canceled (before or after payment)

  5. Timestamps:

    • created_at: Unix timestamp when order was initially created
    • updated_at: Unix timestamp of last order modification
    • Useful for tracking order lifecycle and fulfillment timing

  6. External ID:

    • external_id is a unique identifier for internal tracking
    • Can be used for correlating with external systems
    • Useful for idempotency and duplicate prevention

  7. Use Cases:

    • Display detailed order information to customers
    • Generate packing slips and shipping labels
    • Process order fulfillment with complete item details
    • Customer support inquiries and order tracking
    • Calculate shipping costs based on items and destination
    • Generate invoices with itemized pricing

  8. Error Handling:

    • Returns 404 if order number doesn't exist
    • Returns 403 if order belongs to different merchant
    • Validate order number format before making requests