Coffee Addict Subscriptions.json API

openapi: 3.2.0
info:
  title: Coffeeaddict Nz Subscriptions.json API
  version: '2026-11-04'
  contact:
    url: https://coffeeaddict.nz/api/
  description: 'Operations tagged Subscriptions.json across 2 of this provider''s published API definitions: coffeeaddict-nz-openapi.json, coffeeaddict-nz-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://coffeeaddict.nz
tags:
- name: Subscriptions.json
paths:
  /api/subscriptions.json:
    get:
      operationId: listSubscriptions
      summary: Every roaster's subscription, priced per delivery at each bag size, with…
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  generated_at:
                    type: string
                    format: date-time
                  next_update_after:
                    type: string
                    format: date-time
                    description: Nothing here changes before this time.
                  source:
                    type: string
                  documentation:
                    type: string
                  citation:
                    type: string
                  terms:
                    type: string
                  currency:
                    type: string
                  count:
                    type: integer
                  summary:
                    type: string
                  default_size:
                    type: string
                    description: The size view the page opens on, derived nightly from the data rather than fixed.
                  order:
                    type: string
                  excluded:
                    type: string
                    description: What this comparison leaves out, and why.
                  scope:
                    type: string
                  cadence:
                    type: string
                    description: How often every roaster here is re-read, and how old the oldest reading is. Names the overdue roasters when the promise is not being kept.
                  checked_at_most_every_days:
                    type: integer
                    description: 'The freshness guarantee in days: no roaster on this page goes longer than this between readings. Cache accordingly.'
                  commitment:
                    type: string
                  sizes:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        label:
                          type: string
                          description: The bag size this block priced.
                        count:
                          type: integer
                        method:
                          type: string
                          description: How the ranking was decided.
                        freight:
                          type: string
                          description: What delivery is worth at this size, in a sentence.
                        empty:
                          type: string
                          description: Why the block is empty, when it is.
                        items:
                          type: array
                          items:
                            $ref: '#/components/schemas/Subscription'
                        prepaid_note:
                          type: string
                        prepaid:
                          type: array
                          items:
                            $ref: '#/components/schemas/Subscription'
                          description: Plans bought a whole term in advance. Never ranked with `items`.
      tags:
      - Subscriptions.json
    servers:
    - url: https://coffeeaddict.nz
components:
  schemas:
    Subscription:
      type: object
      title: Subscription
      description: One roaster's cheapest subscription at one bag size, priced to the door.
      additionalProperties: false
      required:
      - roaster_slug
      - roaster
      - url
      - shop_url
      - page
      - bag_size_g
      - bag
      - price_nzd
      - price_from
      - delivery_nzd
      - delivery_published
      - delivery_rule
      - delivered_nzd
      - delivered_exact
      - delivered_per_100g
      - discount_percent
      - every_days
      - kind
      - choose_coffee
      - plan_count
      - commitment
      - term_total_nzd
      - term_deliveries
      - house
      properties:
        roaster_slug:
          type: string
          description: Their key here, and the last part of their page URL.
        roaster:
          type: string
          description: The roaster's name, as they write it.
        url:
          type: string
          description: 'Where to send a reader: a short link on our domain that redirects to the roaster''s subscription listing and counts the click.'
        shop_url:
          type: string
          description: The roaster's own listing, unredirected — so you can see exactly where `url` lands.
        page:
          type: string
          description: Our page for this roaster.
        bag_size_g:
          type: integer
          description: 'The bag this row priced. Rows inside one size view can differ: five roasters sell the small bag as 200g and eight sell it as 250g, and neither is restated as the other.'
        bag:
          type: string
          description: That weight, written out.
        price_nzd:
          type: number
          description: Coffee only, per delivery — the cheapest plan the roaster publishes at this size.
        price_from:
          type: boolean
          description: True when their other coffees at this size cost more, so `price_nzd` is a floor rather than the price.
        delivery_nzd:
          type:
          - number
          - 'null'
          description: 'What freight costs ON THIS ORDER, not their general rate: 0 where the order already clears their free-shipping threshold. Null where they publish no rate that applies to it.'
        delivery_published:
          type: boolean
          description: Whether that figure came from a published rate.
        delivery_rule:
          type: string
          description: The threshold or flat rate that decided it, in words.
        delivered_nzd:
          type: number
          description: 'Coffee plus delivery: what a delivery actually costs.'
        delivered_exact:
          type: boolean
          description: False when `delivered_nzd` is a FLOOR — the roaster publishes no rate below their threshold, or their other coffees cost more. Never treat a floor as a price.
        delivered_per_100g:
          type: number
          description: That total over the grams in the bag. This is what the comparison is ranked on.
        discount_percent:
          type:
          - number
          - 'null'
          description: Measured from the two published prices, never from an advertised percentage. 0 means the roaster sells the plan at shelf price — a real finding. Null means no comparable one-off price existed. The two are never merged.
        every_days:
          type: array
          items:
            type: integer
          description: Every delivery cadence offered at this size, in days. The per-delivery price does not move with it.
        kind:
          type: string
          description: '`subscribe_and_save` (an ordinary bag on repeat, published only at /products/<handle>.js) or `standalone` (the roaster''s own subscription listing).'
        choose_coffee:
          type: boolean
          description: Whether the plan lets the subscriber pick the coffee.
        plan_count:
          type: integer
          description: How many plans the roaster publishes at this size.
        commitment:
          type: string
          description: '`prepaid` (you buy the whole term in advance), `minimum` (rolling, but a stated number of deliveries must arrive before you can cancel) or `rolling`. **`rolling` does NOT mean cancel anytime** — it means the roaster publishes nothing about a minimum term, and almost none of them do outside the checkout.'
        term_total_nzd:
          type:
          - number
          - 'null'
          description: What a prepaid plan charges up front, for `deliveries` deliveries. Null on any other plan. This is the number that decides whether the offer is open to a reader at all, which is why prepaid plans are listed separately from the ranking rather than inside it.
        term_deliveries:
          type:
          - integer
          - 'null'
          description: How many deliveries that cheque covers, or the minimum a `minimum` plan ties you to. Null on a rolling plan.
        house:
          type: boolean
          description: True only for a product of ours. False on every row today, and a house product is never ranked among the roasters' — see /subscriptions/.
x-refined-from:
- coffeeaddict-nz-openapi.json
- coffeeaddict-nz-openapi.yml