> ## Documentation Index
> Fetch the complete documentation index at: https://docs.yabetoopay.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Pricing

> Configure your pricing strategies: one-time payments, recurring subscriptions, trial periods, and multi-currency

## What is a Price?

A **Price** defines how a SKU is billed. It can be a one-time payment or a recurring subscription with different billing intervals.

<Info>
  **Identifier format**: `price_` followed by 36 alphanumeric characters.

  Example: `price_abc123def456ghi789jkl012mno345`
</Info>

## SKU → Price Relationship

A SKU can have multiple prices for different pricing strategies:

```
SKU "Pro Course"
├── Price €99 one-time (single payment)
├── Price €19/month (monthly subscription)
├── Price €199/year (yearly subscription with savings)
└── Price 65,000 XOF one-time (African market)
```

<Note>
  This flexibility allows you to offer multiple payment options for the same product and manage multiple currencies.
</Note>

## Price Attributes

### Main Attributes

| Attribute  | Type    | Description                         |
| ---------- | ------- | ----------------------------------- |
| `id`       | string  | Unique price identifier             |
| `skuId`    | string  | Reference to parent SKU             |
| `amount`   | number  | Amount in whole units               |
| `currency` | string  | Currency code (EUR, XOF, USD, etc.) |
| `type`     | enum    | `one_time` or `recurring`           |
| `active`   | boolean | Price active and usable             |

### Recurring Attributes (subscriptions)

| Attribute              | Type           | Description                                    |
| ---------------------- | -------------- | ---------------------------------------------- |
| `billingInterval`      | enum           | `day`, `week`, `month`, `year`                 |
| `billingIntervalCount` | number         | Number of intervals (e.g., 3 = every 3 months) |
| `trialPeriodDays`      | number \| null | Free trial days                                |

## Pricing Types

<Tabs>
  <Tab title="One-time payment">
    ### One-Time (`one_time`)

    The customer pays once to access the product.

    **Use cases:**

    * One-off purchases
    * Physical products
    * Digital downloads
    * Lifetime access

    ```bash theme={null}
    curl -X POST https://api.yabetoo.com/v1/skus/sku_abc123/prices \
      -H "Authorization: Bearer sk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 99,
        "currency": "EUR",
        "type": "one_time"
      }'
    ```
  </Tab>

  <Tab title="Recurring subscription">
    ### Recurring (`recurring`)

    The customer is billed automatically at regular intervals.

    **Use cases:**

    * SaaS subscriptions
    * Ongoing services
    * Premium access
    * Maintenance

    ```bash theme={null}
    curl -X POST https://api.yabetoo.com/v1/skus/sku_abc123/prices \
      -H "Authorization: Bearer sk_live_..." \
      -H "Content-Type: application/json" \
      -d '{
        "amount": 19,
        "currency": "EUR",
        "type": "recurring",
        "billingInterval": "month",
        "billingIntervalCount": 1,
        "trialPeriodDays": 14
      }'
    ```
  </Tab>
</Tabs>

## Billing Intervals

For recurring prices, define the billing frequency:

| Interval | Count | Description | Example               |
| -------- | ----- | ----------- | --------------------- |
| `day`    | 1     | Daily       | Billed every day      |
| `week`   | 1     | Weekly      | Billed every week     |
| `week`   | 2     | Bi-weekly   | Billed every 2 weeks  |
| `month`  | 1     | Monthly     | Billed every month    |
| `month`  | 3     | Quarterly   | Billed every 3 months |
| `month`  | 6     | Semi-annual | Billed every 6 months |
| `year`   | 1     | Annual      | Billed every year     |

```json theme={null}
// Quarterly billing
{
  "type": "recurring",
  "billingInterval": "month",
  "billingIntervalCount": 3,
  "amount": 45
}
```

## Trial Periods

Offer a free trial period to attract new customers:

```json theme={null}
{
  "type": "recurring",
  "billingInterval": "month",
  "billingIntervalCount": 1,
  "amount": 29,
  "currency": "EUR",
  "trialPeriodDays": 14
}
```

<Steps>
  <Step title="Subscription start">
    Customer signs up and starts their free trial period
  </Step>

  <Step title="Trial period">
    For 14 days, customer has full access without being charged
  </Step>

  <Step title="Trial end">
    At the end of the trial period, the first payment is automatically charged
  </Step>

  <Step title="Recurring cycle">
    Subsequent payments are charged according to the defined interval
  </Step>
</Steps>

<Warning>
  Make sure to clearly inform your customers about the trial duration and the amount that will be charged afterward.
</Warning>

## Multi-Currency Management

Create multiple prices for the same SKU in different currencies:

```json theme={null}
{
  "sku": "sku_formation_pro",
  "prices": [
    {
      "amount": 99,
      "currency": "EUR",
      "type": "one_time"
    },
    {
      "amount": 109,
      "currency": "USD",
      "type": "one_time"
    },
    {
      "amount": 65000,
      "currency": "XOF",
      "type": "one_time"
    }
  ]
}
```

### Supported Currencies

| Code  | Currency        | Country/Region |
| ----- | --------------- | -------------- |
| `EUR` | Euro            | Europe         |
| `USD` | US Dollar       | United States  |
| `XOF` | CFA Franc BCEAO | West Africa    |
| `XAF` | CFA Franc BEAC  | Central Africa |
| `GNF` | Guinean Franc   | Guinea         |
| `CDF` | Congolese Franc | DR Congo       |

<Tip>
  All amounts are expressed in whole units. For example: 99 EUR = €99, 65000 XOF = 65,000 XOF.
</Tip>

## API Response

<Tabs>
  <Tab title="One-time price">
    ```json theme={null}
    {
      "id": "price_abc123def456ghi789",
      "object": "price",
      "skuId": "sku_xyz789abc123def456",
      "amount": 99,
      "currency": "EUR",
      "type": "one_time",
      "billingInterval": null,
      "billingIntervalCount": null,
      "trialPeriodDays": null,
      "active": true,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
    ```
  </Tab>

  <Tab title="Recurring price">
    ```json theme={null}
    {
      "id": "price_def456ghi789jkl012",
      "object": "price",
      "skuId": "sku_xyz789abc123def456",
      "amount": 19,
      "currency": "EUR",
      "type": "recurring",
      "billingInterval": "month",
      "billingIntervalCount": 1,
      "trialPeriodDays": 14,
      "active": true,
      "createdAt": "2024-01-15T10:30:00.000Z",
      "updatedAt": "2024-01-15T10:30:00.000Z"
    }
    ```
  </Tab>
</Tabs>

## Common Operations

### Create a price

```bash theme={null}
curl -X POST https://api.yabetoo.com/v1/skus/sku_abc123/prices \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "amount": 29,
    "currency": "EUR",
    "type": "recurring",
    "billingInterval": "month",
    "billingIntervalCount": 1
  }'
```

### Retrieve a price

```bash theme={null}
curl https://api.yabetoo.com/v1/prices/price_abc123 \
  -H "Authorization: Bearer sk_live_..."
```

### Deactivate a price

<Note>
  Prices cannot be deleted if they are associated with active subscriptions. Use deactivation instead.
</Note>

```bash theme={null}
curl -X PATCH https://api.yabetoo.com/v1/prices/price_abc123 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "active": false
  }'
```

### List prices for a SKU

```bash theme={null}
curl https://api.yabetoo.com/v1/skus/sku_abc123/prices \
  -H "Authorization: Bearer sk_live_..."
```

## Pricing Strategies

### Monthly vs Annual Offer

Offer a discount for annual subscription:

```json theme={null}
{
  "sku": "sku_saas_pro",
  "prices": [
    {
      "amount": 29,
      "currency": "EUR",
      "type": "recurring",
      "billingInterval": "month",
      "billingIntervalCount": 1
    },
    {
      "amount": 290,
      "currency": "EUR",
      "type": "recurring",
      "billingInterval": "year",
      "billingIntervalCount": 1
    }
  ]
}
```

<Tip>
  €29/month vs €290/year represents about 2 free months, which encourages customers to commit for the year.
</Tip>

### Tiered Pricing

Create different SKUs for each service level:

```json theme={null}
{
  "product": "Cloud App",
  "skus": [
    {
      "skuCode": "CLOUD-STARTER",
      "prices": [{ "amount": 9, "currency": "EUR", "type": "recurring", "billingInterval": "month" }]
    },
    {
      "skuCode": "CLOUD-PRO",
      "prices": [{ "amount": 29, "currency": "EUR", "type": "recurring", "billingInterval": "month" }]
    },
    {
      "skuCode": "CLOUD-ENTERPRISE",
      "prices": [{ "amount": 99, "currency": "EUR", "type": "recurring", "billingInterval": "month" }]
    }
  ]
}
```

## Useful Getters

The Price model provides getters to facilitate checks:

```typescript theme={null}
// Check price type
price.isRecurring  // true if type === 'recurring'
price.isOneTime    // true if type === 'one_time'
```

## Best Practices

<AccordionGroup>
  <Accordion title="Amount format">
    Amounts are expressed in whole units of the currency:

    * EUR: 99 = €99
    * USD: 109 = \$109
    * XOF: 65000 = 65,000 XOF
  </Accordion>

  <Accordion title="Active/inactive prices">
    * Deactivate old prices rather than deleting them
    * Keep active prices to the minimum necessary
    * Use different prices for promotions
  </Accordion>

  <Accordion title="Trial periods">
    * 7 to 14 days is generally optimal
    * Too short: not enough time to evaluate
    * Too long: potential revenue loss
  </Accordion>

  <Accordion title="Multi-currency">
    * Adjust prices for each market (not simple conversion)
    * Consider local purchasing power
    * Use psychological pricing (€29 rather than €28.73)
  </Accordion>
</AccordionGroup>

## Next Steps

<CardGroup cols={2}>
  <Card title="Create promotions" icon="percent" href="/en/products/coupons">
    Apply discounts with coupons and promo codes
  </Card>

  <Card title="Manage subscriptions" icon="repeat" href="/en/subscriptions/overview">
    Understand the subscription lifecycle
  </Card>
</CardGroup>