POST /api/v1/services — Create a New Retempo Service

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

string

required

The display name for your service. This value appears in the Retempo dashboard, on invoices, and in checkout sessions presented to payers.

string

A human-readable description of the service. Use this to communicate what the service does or what the subscriber receives.

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.

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.

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.

Show owner fields

string

required

The email address of the owner. Required when using the owner object.

string

The full name of the owner.

string

default:"DEVELOPER"

The role to assign to the owner. Accepted values are DEVELOPER and PAYER.

DEVELOPER — can manage services, plans, and API access.
PAYER — can subscribe to plans and manage billing.

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": []
  }
}

object

The newly created service object.

Show service fields

string

The unique identifier for the service. Use this ID when creating plans, checkout sessions, and settlements.

string

The name you provided in the request.

string

The description you provided in the request, if any.

string

The current lifecycle status: DRAFT, ACTIVE, or DISABLED.

string

The ID of the user assigned as the service owner.

string

ISO 8601 timestamp recording when the service was created.

string

ISO 8601 timestamp recording when the service was last modified.

object

The full owner user object, including id, email, name, and role.

array

An array of payment plans attached to this service. Empty on creation — add plans with Create Plan.

Error Responses

Status	Message	Condition
`400 Bad Request`	`name is required.`	`name` was omitted.
`400 Bad Request`	`status must be one of: DRAFT, ACTIVE, DISABLED.`	An invalid `status` value was provided.
`400 Bad Request`	`ownerId or owner.email is required.`	Neither `ownerId` nor `owner` was provided.
`409 Conflict`	`A 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.

Overview

Services

Payment Plans

Checkout & Invoicing

Settlements

POST /api/v1/services — Create a New Retempo Service

Request Body

Response

Error Responses

Examples

​Request Body

​Response

​Error Responses

​Examples

Request Body

Response

Error Responses

Examples