Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.valued.app/llms.txt

Use this file to discover all available pages before exploring further.

The revenue event is for updating information relating to your customers subscriptions to your product and the invoices you send to them for payment. All revenue events require a customer and a subscription but all other resources are optional. To find more details on the resources please use our Revenue Resources section.

​
Event format

Revenue events are identified with category=revenue.

​
Subscription

{
  "category": "revenue",
  "customer": {
    "id": "123"
  },
  "subscription": {
    "source_key": "sub-321",
    "started_at": 1655384214,
    "status": "active",
    "currency": "USD"
  }
}

​
Subscription with subscription items

{
  "category": "revenue",
  "customer": {
    "id": "valued-cus-312"
  },
  "subscription": {
    "source_key": "sub-321",
    "started_at": 1655384214,
    "status": "active",
    "currency": "USD"
  },
  "subscription_items": [
    {
      "source_key": "sub-item-1",
      "quantity": 2,
      "plan": {
        "source_key": "plan-999-monthly",
        "name": "Solo Plan",
        "price": {
          "source_key": "price-999-monthly",
          "name": "9.99 / month",
          "interval": "month",
          "interval_count": 12,
          "type": "recurring",
          "billing_scheme": "per_unit",
          "currency": "USD",
          "unit_amount": 999,
          "active": true
        }
      }
    },
    {
      "source_key": "sub-item-2",
      "quantity": 1,
      "plan": {
        "source_key": "plan-399-monthly-plus",
        "name": "Solo Plan Plus",
        "price": {
          "source_key": "price-399-monthly-plus",
          "name": "3.99 / month - plus",
          "interval": "month",
          "interval_count": 12,
          "type": "recurring",
          "billing_scheme": "per_unit",
          "currency": "USD",
          "unit_amount": 399,
          "active": true
        }
      }
    }
  ]
}

​
Subscription with multiple tiers

{
  "category": "revenue",
  "customer": {
    "id": "valued-cus-312"
  },
  "subscription": {
    "source_key": "sub-321",
    "started_at": 1655384214,
    "status": "active",
    "currency": "USD"
  },
  "subscription_items": [
    {
      "source_key": "sub-item-1",
      "quantity": 2,
      "plan": {
        "source_key": "plan-999-monthly",
        "name": "Solo Plan",
        "price": {
          "source_key": "price-999-monthly",
          "name": "9.99 / month",
          "interval": "month",
          "interval_count": 12,
          "type": "recurring",
          "billing_scheme": "per_unit",
          "currency": "USD",
          "unit_amount": 999,
          "active": true
        }
      }
    },
    {
      "source_key": "sub-item-2",
      "quantity": 1,
      "plan": {
        "source_key": "plan-399-monthly-plus",
        "name": "Solo Plan Plus",
        "price": {
          "source_key": "price-399-monthly-plus",
          "name": "3.99 / month - plus",
          "interval": "month",
          "interval_count": 12,
          "type": "recurring",
          "billing_scheme": "per_unit",
          "currency": "USD",
          "active": true,
          "tiers": [
            {
              "unit_amount": 399,
              "flat_amount": 100,
              "up_to": 500
            },
            {
              "unit_amount": 199,
              "flat_amount": 299,
              "up_to": 399
            }
          ]
        }
      }
    }
  ]
}

​
Subscription with an invoice

{
  "category": "revenue",
  "customer": {
    "id": "valued-cus-312"
  },
  "subscription": {
    "source_key": "sub-321",
    "started_at": 1655384214,
    "status": "active",
    "currency": "USD"
  },
  "invoice": {
    "source_key": "inv-924",
    "subscription": "sub-321",
    "total": 1000,
    "currency": "USD",
    "status": "paid",
    "finalized_at": 1655384214,
    "paid_at": 1655387324,
    "subtotal": 1000,
    "discount": 0,
    "tax": 230,
    "invoice_items": [
      {
        "source_key": "inv-item-1",
        "quantity": 1,
        "amount": 999,
        "description": "Monthly subscription",
        "amount_excluding_tax": 937,
        "proration": false,
        "period_start": 1655384214,
        "period_end": 1655394214
      },
      {
        "source_key": "inv-item-2",
        "quantity": 3,
        "amount": 399,
        "description": "Bonus",
        "amount_excluding_tax": 237,
        "proration": true,
        "period_start": 1655384214,
        "period_end": 1655394214
      }
    ]
  }
}

​
Syncing Plans and Prices with Tiers

{
  "category": "revenue",
  "plan": {
    "id": "plan-399-monthly-plus",
    "name": "Solo Plan Plus",
    "active": true
  },
  "price": {
    "id": "price-399-monthly-plus",
    "plan": "solo-plan-plus",
    "name": "3.99 / month - plus",
    "interval": "month",
    "interval_count": 12,
    "type": "recurring",
    "billing_scheme": "per_unit",
    "currency": "USD",
    "active": true,
    "tiers": [
      {
        "unit_amount": 399,
        "flat_amount": 100,
        "up_to": 500
      },
      {
        "unit_amount": 199,
        "flat_amount": 299,
        "up_to": 399
      }
    ]
  }
}