Skip to main content
A service represents a product or API you’re billing for — think of it as the top-level entity that holds your payment plans and links to your subscribers. Every checkout session, invoice, and settlement in Retempo traces back to a service. Before you can start collecting USDC, you need at least one service with an owner attached.

​
Creating a service

To create a service, send a POST request to /api/v1/services. You must supply a name and either an owner.email (to create or look up the owner by email) or an ownerId (to reference an existing user). Everything else is optional. 
curl --request POST \
  --url https://api.retempo.xyz/api/v1/services \
  --header 'Content-Type: application/json' \
  --data '{
    "name": "DataStream Pro",
    "description": "Real-time data streaming API for AI agents and analytics pipelines.",
    "status": "DRAFT",
    "owner": {
      "email": "billing@datastream.io",
      "name": "DataStream Team",
      "role": "DEVELOPER"
    }
  }'
A successful response returns the full service object, including the generated id, the resolved owner, and an empty paymentPlans array ready for your first plan: 
{
  "service": {
    "id": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "name": "DataStream Pro",
    "description": "Real-time data streaming API for AI agents and analytics pipelines.",
    "status": "DRAFT",
    "createdAt": "2025-01-14T10:22:00.000Z",
    "owner": {
      "id": "usr_01hx9kz0a3bq1r7fm5ctd2w",
      "email": "billing@datastream.io",
      "name": "DataStream Team",
      "role": "DEVELOPER"
    },
    "paymentPlans": []
  }
}

​
Service statuses

Every service has a status field that controls its visibility and availability for checkout. You can set status at creation time or update it later.
StatusBehavior
DRAFTThe service exists but is not visible to subscribers. Use this while you’re configuring plans.
ACTIVEThe service is live and accepting new checkout sessions. Subscribers can discover and pay for it.
DISABLEDThe service is hidden from new subscribers. Existing subscriptions continue, but no new checkouts can be initiated.
Set status to ACTIVE before creating checkout sessions for the service. A session created against a non-active service will be rejected.

​
Listing services

To retrieve all services on your account, ordered from newest to oldest, send a GET request to /api/v1/services: 
curl --request GET \
  --url https://api.retempo.xyz/api/v1/services \
  --header 'Content-Type: application/json'
The response returns an array of service objects: 
{
  "services": [
    {
      "id": "svc_01hx9kz3v8mq2t4yw6npd7e",
      "name": "DataStream Pro",
      "description": "Real-time data streaming API for AI agents and analytics pipelines.",
      "status": "ACTIVE",
      "createdAt": "2025-01-14T10:22:00.000Z",
      "owner": {
        "id": "usr_01hx9kz0a3bq1r7fm5ctd2w",
        "email": "billing@datastream.io",
        "name": "DataStream Team",
        "role": "DEVELOPER"
      },
      "paymentPlans": [
        {
          "id": "plan_01hx9m1bp4nq3s8zt7vce6r",
          "name": "Pro Monthly",
          "pricingType": "FIXED_RECURRING",
          "billingInterval": "MONTH",
          "amount": "49.000000",
          "currency": "USDC"
        }
      ]
    }
  ]
}

​
Fetching a service

To retrieve a single service along with its owner and all associated payment plans, send a GET request with the service ID: 
curl --request GET \
  --url https://api.retempo.xyz/api/v1/services/svc_01hx9kz3v8mq2t4yw6npd7e \
  --header 'Content-Type: application/json'

{
  "service": {
    "id": "svc_01hx9kz3v8mq2t4yw6npd7e",
    "name": "DataStream Pro",
    "description": "Real-time data streaming API for AI agents and analytics pipelines.",
    "status": "ACTIVE",
    "createdAt": "2025-01-14T10:22:00.000Z",
    "owner": {
      "id": "usr_01hx9kz0a3bq1r7fm5ctd2w",
      "email": "billing@datastream.io",
      "name": "DataStream Team",
      "role": "DEVELOPER"
    },
    "paymentPlans": [
      {
        "id": "plan_01hx9m1bp4nq3s8zt7vce6r",
        "name": "Pro Monthly",
        "pricingType": "FIXED_RECURRING",
        "billingInterval": "MONTH",
        "amount": "49.000000",
        "currency": "USDC",
        "createdAt": "2025-01-14T10:45:00.000Z"
      }
    ]
  }
}