Maxio Offers API

openapi: 3.2.0
info:
  title: Maxio Offers API
  version: '1.0'
  contact:
    email: support@maxio.com
  description: 'Operations tagged Offers across 2 of this provider''s published API definitions: maxio-advanced-billing-openapi31json.json, maxio-advanced-billing-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://{site}.chargify.com
  description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
  variables:
    site:
      default: subdomain
      description: The subdomain for your Advanced Billing site.
- url: https://events.chargify.com/{site}
  description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
  variables:
    site:
      default: subdomain
      description: The subdomain for your Advanced Billing site.
- url: https://{site}.ebilling.maxio.com
  description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
  variables:
    site:
      default: subdomain
      description: The subdomain for your Advanced Billing site.
security:
- BasicAuth: []
tags:
- name: Offers
  description: 'The Offer object packages a combination of products, components, and coupons into a single option that customers can subscribe to, just like a product. Once an offer is defined, the offer can be used as an alternative to a product when creating subscriptions.


    Offers are commonly used to power self-service signup pages without requiring each pricing combination to be built manually. For more information, see Understand Offers.'
paths:
  /offers.json:
    parameters: []
    post:
      tags:
      - Offers
      summary: createOffer
      description: 'Creates an offer within your site.


        Offers allow you to package complicated combinations of products, components and coupons into a convenient package which can then be subscribed to just like products.


        Once an offer is defined it can be used as an alternative to the product when creating subscriptions.


        For more information, see Offers in the product documentation.


        ## Using a Product Price Point


        You can optionally pass in a `product_price_point_id` that corresponds with the `product_id` and the offer will use that price point. If a `product_price_point_id` is not passed in, the product''s default price point will be used.'
      operationId: createOffer
      parameters: []
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              allOf:
              - $ref: '#/components/schemas/CreateOfferRequest'
              - examples:
                - offer:
                    name: Solo
                    handle: han_shot_first
                    description: A Star Wars Story
                    product_id: 31
                    product_price_point_id: 102
                    components:
                    - component_id: 24
                      starting_quantity: 1
                    coupons:
                    - DEF456
              contentMediaType: application/json
            examples:
              Example:
                value:
                  offer:
                    name: Solo
                    handle: han_shot_first
                    description: A Star Wars Story
                    product_id: 31
                    product_price_point_id: 102
                    components:
                    - component_id: 24
                      starting_quantity: 1
                    coupons:
                    - DEF456
        required: false
      responses:
        '201':
          description: Created
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/OfferResponse'
                - examples:
                  - offer:
                      id: 3
                      site_id: 2
                      product_family_id: 4
                      product_family_name: Chargify
                      product_id: 31
                      product_name: 30-Day Square Trial
                      product_price_in_cents: 2000
                      product_revisable_number: 0
                      name: Solo
                      handle: han_shot_first
                      description: A Star Wars Story
                      created_at: '2018-06-08T14:51:52-04:00'
                      updated_at: '2018-06-08T14:51:52-04:00'
                      archived_at: null
                      product_price_point_name: Default
                      offer_items:
                      - component_id: 24
                        component_name: Invoices
                        component_unit_price: '3.0'
                        price_point_id: 104
                        price_point_name: Original
                        starting_quantity: '1.0'
                        editable: false
                      offer_discounts:
                      - coupon_id: 3
                        coupon_code: DEF456
                        coupon_name: IB Loyalty
                contentMediaType: application/json
              examples:
                Example:
                  value:
                    offer:
                      id: 3
                      site_id: 2
                      product_family_id: 4
                      product_family_name: Chargify
                      product_id: 31
                      product_name: 30-Day Square Trial
                      product_price_in_cents: 2000
                      product_revisable_number: 0
                      name: Solo
                      handle: han_shot_first
                      description: A Star Wars Story
                      created_at: '2018-06-08T14:51:52-04:00'
                      updated_at: '2018-06-08T14:51:52-04:00'
                      archived_at: null
                      product_price_point_name: Default
                      offer_items:
                      - component_id: 24
                        component_name: Invoices
                        component_unit_price: '3.0'
                        price_point_id: 104
                        price_point_name: Original
                        starting_quantity: '1.0'
                        editable: false
                      offer_discounts:
                      - coupon_id: 3
                        coupon_code: DEF456
                        coupon_name: IB Loyalty
        '422':
          description: Unprocessable Entity (WebDAV)
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorArrayMapResponse1'
                - examples:
                  - errors:
                      components:
                      - 'starting_quantity for an On/Off component can only be ''1'' or ''0'': 24'
                contentMediaType: application/json
              examples:
                Example:
                  value:
                    errors:
                      components:
                      - 'starting_quantity for an On/Off component can only be ''1'' or ''0'': 24'
      deprecated: false
    get:
      tags:
      - Offers
      summary: listOffers
      description: Lists offers for a site.
      operationId: listOffers
      parameters:
      - name: page
        in: query
        description: 'Result records are organized in pages. By default, the first page of results is displayed. The page parameter specifies a page number of results to fetch. You can start navigating through the pages to consume the results. You do this by passing in a page parameter. Retrieve the next page by adding ?page=2 to the query string. If there are no results to return, then an empty result set will be returned.

          Use in query `page=1`.'
        style: form
        explode: true
        schema:
          minimum: 1.0
          type: integer
          contentEncoding: int32
          default: 1
          examples:
          - 1
      - name: per_page
        in: query
        description: 'This parameter indicates how many records to fetch in each request. Default value is 20. The maximum allowed values is 200; any per_page value over 200 will be changed to 200.

          Use in query `per_page=200`.'
        style: form
        explode: true
        schema:
          maximum: 200.0
          type: integer
          contentEncoding: int32
          default: 20
          examples:
          - 50
      - name: include_archived
        in: query
        description: 'Include archived products. Use in query: `include_archived=true`.'
        style: form
        explode: true
        schema:
          type: boolean
          examples:
          - true
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ListOffersResponse'
                - examples:
                  - offers:
                    - id: 239
                      site_id: 48110
                      product_family_id: 1025627
                      product_family_name: Gold
                      product_id: 110
                      product_name: Pro
                      product_price_in_cents: 1000
                      product_revisable_number: 0
                      product_price_point_id: 138
                      product_price_point_name: Default
                      name: Third Offer
                      handle: third
                      description: ''
                      created_at: '2018-08-03T09:56:11-05:00'
                      updated_at: '2018-08-03T09:56:11-05:00'
                      archived_at: null
                      offer_items:
                      - component_id: 426665
                        component_name: Database Size (GB)
                        component_unit_price: '1.0'
                        price_point_id: 149438
                        price_point_name: Auto-created
                        starting_quantity: '0.0'
                        editable: false
                      offer_discounts:
                      - coupon_id: 234
                        coupon_code: GR8_CUSTOMER
                        coupon_name: Multi-service Discount
                      offer_signup_pages:
                      - id: 356482
                        nickname: ggoods
                        enabled: true
                        return_url: ''
                        return_params: ''
                        url: https://general-goods.chargifypay.com/subscribe/hjpvhnw63tzy
                contentMediaType: application/json
              examples:
                Example:
                  value:
                    offers:
                    - id: 239
                      site_id: 48110
                      product_family_id: 1025627
                      product_family_name: Gold
                      product_id: 110
                      product_name: Pro
                      product_price_in_cents: 1000
                      product_revisable_number: 0
                      product_price_point_id: 138
                      product_price_point_name: Default
                      name: Third Offer
                      handle: third
                      description: ''
                      created_at: '2018-08-03T09:56:11-05:00'
                      updated_at: '2018-08-03T09:56:11-05:00'
                      archived_at: null
                      offer_items:
                      - component_id: 426665
                        component_name: Database Size (GB)
                        component_unit_price: '1.0'
                        price_point_id: 149438
                        price_point_name: Auto-created
                        starting_quantity: '0.0'
                        editable: false
                      offer_discounts:
                      - coupon_id: 234
                        coupon_code: GR8_CUSTOMER
                        coupon_name: Multi-service Discount
                      offer_signup_pages:
                      - id: 356482
                        nickname: ggoods
                        enabled: true
                        return_url: ''
                        return_params: ''
                        url: https://general-goods.chargifypay.com/subscribe/hjpvhnw63tzy
        '422':
          description: Unprocessable Entity (WebDAV)
          headers: {}
          content:
            application/json:
              schema:
                allOf:
                - $ref: '#/components/schemas/ErrorListResponse1'
                - description: Error which contains list of messages.
                  examples:
                  - errors:
                    - 'invalid page: -1'
                contentMediaType: application/json
              examples:
                Invalid-Page:
                  value:
                    errors:
                    - 'invalid page: -1'
      deprecated: false
    servers:
    - url: https://{site}.chargify.com
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://{site}.ebilling.maxio.com
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
  /offers/{offer_id}.json:
    parameters: []
    get:
      tags:
      - Offers
      summary: readOffer
      description: Returns a specific offer's attributes. This is different from listing all offers for a site, as it requires an `offer_id`.
      operationId: readOffer
      parameters:
      - name: offer_id
        in: path
        description: The Chargify id of the offer
        required: true
        schema:
          type: integer
          contentEncoding: int32
      responses:
        '200':
          description: OK
          headers: {}
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OfferResponse'
      deprecated: false
    servers:
    - url: https://{site}.chargify.com
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://{site}.ebilling.maxio.com
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
  /offers/{offer_id}/archive.json:
    parameters: []
    put:
      tags:
      - Offers
      summary: archiveOffer
      description: Archives an existing offer. Please provide an `offer_id` in order to archive the correct item.
      operationId: archiveOffer
      parameters:
      - name: offer_id
        in: path
        description: The Chargify id of the offer
        required: true
        schema:
          type: integer
          contentEncoding: int32
      responses:
        '200':
          description: OK
          headers: {}
          content: {}
      deprecated: false
    servers:
    - url: https://{site}.chargify.com
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://{site}.ebilling.maxio.com
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
  /offers/{offer_id}/unarchive.json:
    parameters: []
    put:
      tags:
      - Offers
      summary: unarchiveOffer
      description: Unarchives a previously archived offer. Please provide an `offer_id` in order to unarchive the correct item.
      operationId: unarchiveOffer
      parameters:
      - name: offer_id
        in: path
        description: The Chargify id of the offer
        required: true
        schema:
          type: integer
          contentEncoding: int32
      responses:
        '200':
          description: OK
          headers: {}
          content: {}
      deprecated: false
    servers:
    - url: https://{site}.chargify.com
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Default Advanced Billing environment hosted in US. Valid for the majority of our customers.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://{site}.ebilling.maxio.com
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
    - url: https://events.chargify.com/{site}
      description: Advanced Billing environment hosted in EU. Use only when you requested EU hosting for your AB account.
      variables:
        site:
          default: subdomain
          description: The subdomain for your Advanced Billing site.
components:
  schemas:
    ErrorListResponse1:
      title: ErrorListResponse1
      required:
      - errors
      type: object
      properties:
        errors:
          type: array
          items:
            type: string
          description: ''
      description: Error which contains list of messages.
    CurrencyPrice:
      title: CurrencyPrice
      type: object
      properties:
        id:
          type: integer
          contentEncoding: int32
        currency:
          type: string
        price:
          type: number
        formatted_price:
          type: string
        price_id:
          type: integer
          contentEncoding: int32
        price_point_id:
          type: integer
          contentEncoding: int32
        product_price_point_id:
          type: integer
          contentEncoding: int32
        role:
          allOf:
          - $ref: '#/components/schemas/CurrencyPriceRole'
          - description: Role for the price.
    OfferSignupPage:
      title: OfferSignupPage
      type: object
      properties:
        id:
          type: integer
          contentEncoding: int32
        nickname:
          type: string
        enabled:
          type: boolean
        return_url:
          type: string
        return_params:
          type: string
        url:
          type: string
    CreateOfferRequest:
      title: CreateOfferRequest
      required:
      - offer
      type: object
      properties:
        offer:
          $ref: '#/components/schemas/CreateOffer'
    CurrencyPriceRole:
      title: CurrencyPriceRole
      enum:
      - baseline
      - trial
      - initial
      type: string
      description: Role for the price.
    IntervalUnit:
      title: IntervalUnit
      enum:
      - day
      - month
      type: string
    ErrorArrayMapResponse1:
      title: ErrorArrayMapResponse1
      type: object
      properties:
        errors:
          type: object
          additionalProperties: {}
    OfferDiscount:
      title: OfferDiscount
      type: object
      properties:
        coupon_code:
          type: string
        coupon_id:
          type: integer
          contentEncoding: int32
        coupon_name:
          type: string
    OfferItem:
      title: OfferItem
      type: object
      properties:
        component_id:
          type: integer
          contentEncoding: int32
        price_point_id:
          type: integer
          contentEncoding: int32
        starting_quantity:
          type: string
        editable:
          type: boolean
        component_unit_price:
          type: string
        component_name:
          type: string
        price_point_name:
          type: string
        currency_prices:
          type: array
          items:
            $ref: '#/components/schemas/CurrencyPrice'
          description: ''
        interval:
          type: integer
          description: The numerical interval. e.g., an interval of '30' coupled with an interval_unit of day would mean this component price point would renew every 30 days. This property is only available for sites with Multifrequency enabled.
          contentEncoding: int32
        interval_unit:
          allOf:
          - oneOf:
            - {}
            - $ref: '#/components/schemas/IntervalUnit'
          - description: A string representing the interval unit for this component price point, either month or day. This property is only available for sites with Multifrequency enabled.
    OfferResponse:
      title: OfferResponse
      type: object
      properties:
        offer:
          $ref: '#/components/schemas/Offer'
    Offer:
      title: Offer
      type: object
      properties:
        id:
          type: integer
          contentEncoding: int32
        site_id:
          type: integer
          contentEncoding: int32
        product_family_id:
          type: integer
          contentEncoding: int32
        product_id:
          type: integer
          contentEncoding: int32
        product_price_point_id:
          type: integer
          contentEncoding: int32
        product_revisable_number:
          type: integer
          contentEncoding: int32
        name:
          type: string
        handle:
          type: string
        description:
          type:
          - string
          - 'null'
        created_at:
          type: string
          contentEncoding: date-time
        updated_at:
          type: string
          contentEncoding: date-time
        archived_at:
          type:
          - string
          - 'null'
          contentEncoding: date-time
        offer_items:
          type: array
          items:
            $ref: '#/components/schemas/OfferItem'
          description: ''
        offer_discounts:
          type: array
          items:
            $ref: '#/components/schemas/OfferDiscount'
          description: ''
        product_family_name:
          type: string
        product_name:
          type: string
        product_price_point_name:
          type: string
        product_price_in_cents:
          type: integer
          contentEncoding: int64
        offer_signup_pages:
          type: array
          items:
            $ref: '#/components/schemas/OfferSignupPage'
          description: ''
    CreateOfferComponent:
      title: CreateOfferComponent
      type: object
      properties:
        component_id:
          type: integer
          contentEncoding: int32
        price_point_id:
          type: integer
          contentEncoding: int32
        starting_quantity:
          type: integer
          contentEncoding: int32
    ListOffersResponse:
      title: ListOffersResponse
      type: object
      properties:
        offers:
          type: array
          items:
            $ref: '#/components/schemas/Offer'
          description: ''
    CreateOffer:
      title: CreateOffer
      required:
      - name
      - handle
      - product_id
      type: object
      properties:
        name:
          type: string
        handle:
          type: string
        description:
          type: string
        product_id:
          type: integer
          contentEncoding: int32
        product_price_point_id:
          type: integer
          contentEncoding: int32
        components:
          type: array
          items:
            $ref: '#/components/schemas/CreateOfferComponent'
          description: ''
        coupons:
          type: array
          items:
            type: string
          description: ''
  securitySchemes:
    BasicAuth:
      type: http
      description: The `username` is a Maxio Chargify API key. The `password` is `x`.
      scheme: basic
x-refined-from:
- maxio-advanced-billing-openapi31json.json
- maxio-advanced-billing-openapi.yml
x-provenance:
  method: harvested
  publisher: Maxio
  source: https://developers.maxio.com/static/exports/maxio-advanced-billing-openapi31json.json
  note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
    stamped by stamp-openapi-provenance.py (roadmap#793)