---
title: "Add to your cart"
method: POST
path: "/api/v1/cart/items"
tags: ["Cart"]
---

# Add to your cart

`POST /api/v1/cart/items`

## Request

- Base URL: `https://spoofy.social`
- URL: `https://spoofy.social/api/v1/cart/items`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `better-auth.session_token`

Add a line — checked as it goes in (on sale, the link fits, the amount and order fields are right). The same plain service for the same link again adds to that line’s amount. `items` adds several at once (up to 25, as a signed-out browser’s cart on sign-in): a line that cannot go in is skipped and listed in `skipped`. A cart holds up to 25 lines; done-for-you services are checked out on their own.

## Request body

- union
  - BatchItem: One order: what `POST /api/v1/orders` takes, plus an optional schedule.
    - `service` integer, required
    - `link` string, required
    - `quantity` integer: How many. Left out where the inputs count it (comments, usernames) or it is fixed (packages, subscriptions).
    - `inputs` OrderInputs: Order fields, for services with `input.fields`. Text we post for you is checked first (see text_blocked).
      - `comments` union: Custom comments: one per line (or a list), each different. Their number is the quantity.
        - string[]
        - string
      - `usernames` union: Mentions: the accounts to mention, one per line (or a list), at most 50. Their number is the quantity.
        - string[]
        - string
      - `hashtag` string: Mentions by hashtag: one hashtag, e.g. "#yourbrand".
      - `username` string: An account (handle or profile link): whose followers get mentioned, whose comment gets the likes, or a subscription’s account.
      - `answer_number` integer: Poll votes: the option to vote for, 1 = the first (GET /api/v1/polls reads the options).
      - `runs` integer: Spread the order over this many runs; `quantity` is then per run and you pay for quantity × runs. Only where `input.spread` is true.
      - `interval` integer: Minutes between runs.
      - `min` integer: Subscriptions: the least each new post gets.
      - `max` integer: Subscriptions: the most each new post gets.
      - `posts` integer: Subscriptions: how many of your future posts it covers.
      - `old_posts` integer: Subscriptions: also this many of your latest posts.
      - `delay` 0 | 5 | 10 | 15 | 20 | 30 | 40 | 50 | 60 | 90 | 120 | 150 | 180 | 210 | 240 | 270 | 300 | 360 | 420 | 480 | 540 | 600: Subscriptions: minutes after a post goes up before it starts.
      - `expiry` string, date: Subscriptions: the last day (optional, up to a year ahead).
    - `details` object: Done-for-you services only (batch, not the cart): the answers to the service’s `form`.
    - `schedule` ItemSchedule: Deliver this order on a schedule instead of all at once: it becomes an automation (the same fields as `POST /api/v1/automations`, without service, link and quantity). `quantity` is then the automation’s — all of it for `spread`, `split` or `scheduled`, each time for `recurring`. Each part is charged when it goes.
      - `kind` 'spread' | 'scheduled' | 'recurring' | 'split', required
      - `start_at` string: ISO 8601 with an offset; a later start.
      - `timezone` string: IANA zone, e.g. "America/Costa_Rica".
      - `runs` integer: spread: this many runs, `interval_minutes` apart.
      - `interval_minutes` number
      - `over` string: spread: over "1d", "3d", "7d" or "14d" in natural parts.
      - `pace` string: spread: even, steady, front or back.
      - `natural` boolean
      - `every` unknown
      - `times` integer: recurring: how many times.
  - object
    - `items` BatchItem[], required
      - `service` integer, required
      - `link` string, required
      - `quantity` integer: How many. Left out where the inputs count it (comments, usernames) or it is fixed (packages, subscriptions).
      - `inputs` OrderInputs: Order fields, for services with `input.fields`. Text we post for you is checked first (see text_blocked).
        - `comments` union: Custom comments: one per line (or a list), each different. Their number is the quantity.
          - string[]
          - string
        - `usernames` union: Mentions: the accounts to mention, one per line (or a list), at most 50. Their number is the quantity.
          - string[]
          - string
        - `hashtag` string: Mentions by hashtag: one hashtag, e.g. "#yourbrand".
        - `username` string: An account (handle or profile link): whose followers get mentioned, whose comment gets the likes, or a subscription’s account.
        - `answer_number` integer: Poll votes: the option to vote for, 1 = the first (GET /api/v1/polls reads the options).
        - `runs` integer: Spread the order over this many runs; `quantity` is then per run and you pay for quantity × runs. Only where `input.spread` is true.
        - `interval` integer: Minutes between runs.
        - `min` integer: Subscriptions: the least each new post gets.
        - `max` integer: Subscriptions: the most each new post gets.
        - `posts` integer: Subscriptions: how many of your future posts it covers.
        - `old_posts` integer: Subscriptions: also this many of your latest posts.
        - `delay` 0 | 5 | 10 | 15 | 20 | 30 | 40 | 50 | 60 | 90 | 120 | 150 | 180 | 210 | 240 | 270 | 300 | 360 | 420 | 480 | 540 | 600: Subscriptions: minutes after a post goes up before it starts.
        - `expiry` string, date: Subscriptions: the last day (optional, up to a year ahead).
      - `details` object: Done-for-you services only (batch, not the cart): the answers to the service’s `form`.
      - `schedule` ItemSchedule: Deliver this order on a schedule instead of all at once: it becomes an automation (the same fields as `POST /api/v1/automations`, without service, link and quantity). `quantity` is then the automation’s — all of it for `spread`, `split` or `scheduled`, each time for `recurring`. Each part is charged when it goes.
        - `kind` 'spread' | 'scheduled' | 'recurring' | 'split', required
        - `start_at` string: ISO 8601 with an offset; a later start.
        - `timezone` string: IANA zone, e.g. "America/Costa_Rica".
        - `runs` integer: spread: this many runs, `interval_minutes` apart.
        - `interval_minutes` number
        - `over` string: spread: over "1d", "3d", "7d" or "14d" in natural parts.
        - `pace` string: spread: even, steady, front or back.
        - `natural` boolean
        - `every` unknown
        - `times` integer: recurring: how many times.

## Response `201`

Added.

- object
  - `cart` Cart
    - `items` CartItem[]
      - `id` string
      - `service` object, nullable: null when the service is no longer on sale.
      - `link` string
      - `linkInfo` object, nullable
        - `platform` string
        - `kind` string
        - `label` string
      - `linkKey` string: The tidied link the cart groups by.
      - `quantity` integer, nullable
      - `units` integer, nullable: What is charged: the quantity, or what the order fields come to.
      - `inputs` object, nullable
      - `schedule` ItemSchedule: Deliver this order on a schedule instead of all at once: it becomes an automation (the same fields as `POST /api/v1/automations`, without service, link and quantity). `quantity` is then the automation’s — all of it for `spread`, `split` or `scheduled`, each time for `recurring`. Each part is charged when it goes.
        - `kind` 'spread' | 'scheduled' | 'recurring' | 'split', required
        - `start_at` string: ISO 8601 with an offset; a later start.
        - `timezone` string: IANA zone, e.g. "America/Costa_Rica".
        - `runs` integer: spread: this many runs, `interval_minutes` apart.
        - `interval_minutes` number
        - `over` string: spread: over "1d", "3d", "7d" or "14d" in natural parts.
        - `pace` string: spread: even, steady, front or back.
        - `natural` boolean
        - `every` unknown
        - `times` integer: recurring: how many times.
      - `total` string, nullable: Its price now, USD (a schedule: about its whole plan; the exact plan rounds each part up).
      - `totalMicros` string, nullable
      - `delivery` string, nullable: The delivery estimate in words.
      - `plan` string, nullable: A schedule in words.
      - `problem` object, nullable: Why it cannot go as it is (`code`, `message`), else null.
        - `code` string
        - `message` string
      - `createdAt` string, date-time
    - `count` integer
    - `total` string: Today’s price of the lines that can go. USD as a decimal string.
    - `totalMicros` string
    - `balance` string: Your balance. USD as a decimal string.
  - `added` string[]
  - `skipped` object[]

## Other responses

- `400`: The line cannot go in.
- `401`: No valid API key or session.
- `409`: The cart is full.
- `413`: The request body is too big (uploads up to 4 MB, everything else up to 64 KB).
- `429`: Slow down: too many requests in a short time. Wait `Retry-After` seconds and carry on.

---

[API](https://skmtc.dev/spoofy/apis/spoofy-api.md) · [All operations](https://skmtc.dev/spoofy/apis/spoofy-api/llms.txt) · [OpenAPI document](https://skmtc.dev/spoofy/apis/spoofy-api/revisions/58adc986f826?raw)