Skip to main content
Use this endpoint to create a new service in Retempo. A service is the top-level resource that holds payment plans, checkout sessions, and settlement records. You can attach an owner to the service either by referencing an existing user ID with ownerId, or by passing an owner object to create or upsert an owner by email address. 
POST https://api.retempo.xyz/api/v1/services

​
Request Body

​
name
string
required
The display name for your service. This value appears in the Retempo dashboard, on invoices, and in checkout sessions presented to payers.
​
description
string
A human-readable description of the service. Use this to communicate what the service does or what the subscriber receives.
​
status
string
default:"DRAFT"
The initial lifecycle status of the service. Accepted values are DRAFT, ACTIVE, and DISABLED.
  • DRAFT — the service is created but not yet visible for checkout.
  • ACTIVE — the service is live and can accept new subscribers.
  • DISABLED — the service is deactivated and cannot accept new checkout sessions.
​
ownerId
string
The ID of an existing Retempo user to assign as the service owner. Use this field or the owner object — not both. If both are provided, ownerId takes precedence.
​
owner
object
An object to create or upsert a service owner by email. If a user with the given email already exists, Retempo links that user to the service. If no user exists, a new one is created.
Supply either ownerId or the owner object — not both. If neither is provided, the request returns 400 with "ownerId or owner.email is required.". If you need to associate an owner you have already created, prefer ownerId to avoid accidental upserts.

​
Response

A successful request returns HTTP 201 Created with the new service object. 
{
  "service": {
    "id": "clz1abc2def3ghi4",
    "name": "DataStream Pro",
    "description": "Real-time data streaming API",
    "status": "ACTIVE",
    "ownerId": "clz1owner123",
    "createdAt": "2025-06-01T10:00:00.000Z",
    "updatedAt": "2025-06-01T10:00:00.000Z",
    "owner": {
      "id": "clz1owner123",
      "email": "dev@example.com",
      "name": "Alice Dev",
      "role": "DEVELOPER"
    },
    "paymentPlans": []
  }
}
​
service
object
The newly created service object.

​
Error Responses

StatusMessageCondition
400 Bad Requestname is required.name was omitted.
400 Bad Requeststatus must be one of: DRAFT, ACTIVE, DISABLED.An invalid status value was provided.
400 Bad RequestownerId or owner.email is required.Neither ownerId nor owner was provided.
409 ConflictA database record with these unique fields already exists.A conflicting record already exists.

​
Examples

Create a service with a new owner: 
curl -X POST https://api.retempo.xyz/api/v1/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DataStream Pro",
    "description": "Real-time data streaming API",
    "status": "ACTIVE",
    "owner": {
      "email": "dev@example.com",
      "name": "Alice Dev",
      "role": "DEVELOPER"
    }
  }'
Create a service assigned to an existing owner: 
curl -X POST https://api.retempo.xyz/api/v1/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DataStream Pro",
    "status": "DRAFT",
    "ownerId": "clz1owner123"
  }'
Start services in DRAFT status while you configure payment plans. Switch to ACTIVE only when you are ready to accept subscribers.