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

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

> POST /api/v1/services — creates a new service in Retempo. Accepts name, description, status, and owner details. Returns the created service object.

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

<ParamField body="name" type="string" required>
  The display name for your service. This value appears in the Retempo dashboard, on invoices, and in checkout sessions presented to payers.
</ParamField>

<ParamField body="description" type="string">
  A human-readable description of the service. Use this to communicate what the service does or what the subscriber receives.
</ParamField>

<ParamField body="status" type="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.
</ParamField>

<ParamField body="ownerId" type="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.
</ParamField>

<ParamField body="owner" type="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.

  <Expandable title="owner fields">
    <ParamField body="owner.email" type="string" required>
      The email address of the owner. Required when using the `owner` object.
    </ParamField>

    <ParamField body="owner.name" type="string">
      The full name of the owner.
    </ParamField>

    <ParamField body="owner.role" type="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.
    </ParamField>
  </Expandable>
</ParamField>

<Note>
  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.
</Note>

## Response

A successful request returns HTTP `201 Created` with the new service object.

```json theme={null}
{
  "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": []
  }
}
```

<ResponseField name="service" type="object">
  The newly created service object.

  <Expandable title="service fields">
    <ResponseField name="service.id" type="string">
      The unique identifier for the service. Use this ID when creating plans, checkout sessions, and settlements.
    </ResponseField>

    <ResponseField name="service.name" type="string">
      The name you provided in the request.
    </ResponseField>

    <ResponseField name="service.description" type="string">
      The description you provided in the request, if any.
    </ResponseField>

    <ResponseField name="service.status" type="string">
      The current lifecycle status: `DRAFT`, `ACTIVE`, or `DISABLED`.
    </ResponseField>

    <ResponseField name="service.ownerId" type="string">
      The ID of the user assigned as the service owner.
    </ResponseField>

    <ResponseField name="service.createdAt" type="string">
      ISO 8601 timestamp recording when the service was created.
    </ResponseField>

    <ResponseField name="service.updatedAt" type="string">
      ISO 8601 timestamp recording when the service was last modified.
    </ResponseField>

    <ResponseField name="service.owner" type="object">
      The full owner user object, including `id`, `email`, `name`, and `role`.
    </ResponseField>

    <ResponseField name="service.paymentPlans" type="array">
      An array of payment plans attached to this service. Empty on creation — add plans with [Create Plan](/api/plans/create).
    </ResponseField>
  </Expandable>
</ResponseField>

### 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:**

```bash theme={null}
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:**

```bash theme={null}
curl -X POST https://api.retempo.xyz/api/v1/services \
  -H "Content-Type: application/json" \
  -d '{
    "name": "DataStream Pro",
    "status": "DRAFT",
    "ownerId": "clz1owner123"
  }'
```

<Tip>
  Start services in `DRAFT` status while you configure payment plans. Switch to `ACTIVE` only when you are ready to accept subscribers.
</Tip>