Upsun Orders API

openapi: 3.0.1
info:
  title: Upsun.com Rest Add-ons Orders API
  version: '1.0'
  contact:
    name: Support
    url: https://upsun.com/contact-us/
  termsOfService: https://upsun.com/trust-center/legal/tos/
  description: "# Introduction\n\nUpsun, formerly Platform.sh, is a container-based Platform-as-a-Service. Our main API\nis simply Git. With a single `git push` and a couple of YAML files in\nyour repository you can deploy an arbitrarily complex cluster.\nEvery [**Project**](#tag/Project) can have multiple applications (PHP,\nNode.js, Python, Ruby, Go, etc.) and managed, automatically\nprovisioned services (databases, message queues, etc.).\n\nEach project also comes with multiple concurrent\nlive staging/development [**Environments**](#tag/Environment).\nThese ephemeral development environments\nare automatically created every time you push a new branch or create a\npull request, and each has a full copy of the data of its parent branch,\nwhich is created on-the-fly in seconds.\n\nOur Git implementation supports integrations with third party Git\nproviders such as GitHub, Bitbucket, or GitLab, allowing you to simply\nintegrate Upsun into your existing workflow.\n\n## Using the REST API\n\nIn addition to the Git API, we also offer a REST API that allows you to manage\nevery aspect of the platform, from managing projects and environments,\nto accessing accounts and subscriptions, to creating robust workflows\nand integrations with your CI systems and internal services.\n\nThese API docs are generated from a standard **OpenAPI (Swagger)** Specification document\nwhich you can find here in [YAML](openapispec-upsun.yaml) and in [JSON](openapispec-upsun.json) formats.\n\nThis RESTful API consumes and produces HAL-style JSON over HTTPS,\nand any REST library can be used to access it. On GitHub, we also host\na few API libraries that you can use to make API access easier, such as our\n[PHP API client](https://github.com/upsun/upsun-sdk-php).\n\nIn order to use the API you will first need to have an [Upsun account](https://auth.upsun.com/register/) \nand [create an API Token](https://docs.upsun.com/anchors/cli/api-token/).\n\n# Authentication\n\n## OAuth2\n\nAPI authentication is done with OAuth2 access tokens.\n\n### API tokens\n\nYou can use an API token as one way to get an OAuth2 access token. This\nis particularly useful in scripts, e.g. for CI pipelines.\n\nTo create an API token, go to the \"API Tokens\" section\nof the \"Account Settings\" tab on the [Console](https://console.upsun.com).\n\nTo exchange this API token for an access token, a `POST` request\nmust be made to `https://auth.upsun.com/oauth2/token`.\n\nThe request will look like this in cURL:\n\n<pre>\ncurl -u platform-api-user: \\\n    -d 'grant_type=api_token&amp;api_token=<em><b>API_TOKEN</b></em>' \\\n    https://auth.upsun.com/oauth2/token\n</pre>\n\nThis will return a \"Bearer\" access token that\ncan be used to authenticate further API requests, for example:\n\n<pre>\n{\n    \"access_token\": \"<em><b>abcdefghij1234567890</b></em>\",\n    \"expires_in\": 900,\n    \"token_type\": \"bearer\"\n}\n</pre>\n\n### Using the Access Token\n\nTo authenticate further API requests, include this returned bearer token\nin the `Authorization` header. For example, to retrieve a list of\n[Projects](#tag/Project)\naccessible by the current user, you can make the following request\n(substituting the dummy token for your own):\n\n<pre>\ncurl -H \"Authorization: Bearer <em><b>abcdefghij1234567890</b></em>\" \\\n    https://api.upsun.com/projects\n</pre>\n\n# HAL Links\n\nMost endpoints in the API return fields which defines a HAL\n(Hypertext Application Language) schema for the requested endpoint.\nThe particular objects returns and their contents can vary by endpoint.\nThe payload examples we give here for the requests do not show these\nelements. These links can allow you to create a fully dynamic API client\nthat does not need to hardcode any method or schema.\n\nUnless they are used for pagination we do not show the HAL links in the\npayload examples in this documentation for brevity and as their content\nis contextual (based on the permissions of the user).\n\n## _links Objects\n\nMost endpoints that respond to `GET` requests will include a `_links` object\nin their response. The `_links` object contains a key-object pair labelled `self`, which defines\ntwo further key-value pairs:\n\n* `href` - A URL string referring to the fully qualified name of the returned object. For many endpoints, this will be the direct link to the API endpoint on the region gateway, rather than on the general API gateway. This means it may reference a host of, for example, `eu-2.platform.sh` rather than `api.upsun.com`.\n* `meta` - An object defining the OpenAPI Specification (OAS) [schema object](https://swagger.io/specification/#schemaObject) of the component returned by the endpoint.\n\nThere may be zero or more other fields in the `_links` object resembling fragment identifiers\nbeginning with a hash mark, e.g. `#edit` or `#delete`. Each of these keys\nrefers to a JSON object containing two key-value pairs:\n\n* `href` - A URL string referring to the path name of endpoint which can perform the action named in the key.\n* `meta` - An object defining the OAS schema of the endpoint. This consists of a key-value pair, with the key defining an HTTP method and the value defining the [operation object](https://swagger.io/specification/#operationObject) of the endpoint.\n\nTo use one of these HAL links, you must send a new request to the URL defined\nin the `href` field which contains a body defined the schema object in the `meta` field.\n\nFor example, if you make a request such as `GET /projects/abcdefghij1234567890`, the `_links`\nobject in the returned response will include the key `#delete`. That object\nwill look something like this fragment:\n\n```\n\"#delete\": {\n    \"href\": \"/api/projects/abcdefghij1234567890\",\n    \"meta\": {\n        \"delete\": {\n            \"responses\": {\n                . . . // Response definition omitted for space\n            },\n            \"parameters\": []\n        }\n    }\n}\n```\n\nTo use this information to delete a project, you would then send a `DELETE`\nrequest to the endpoint `https://api.upsun.com/api/projects/abcdefghij1234567890`\nwith no body or parameters to delete the project that was originally requested.\n\n## _embedded Objects\n\nRequests to endpoints which create or modify objects, such as `POST`, `PATCH`, or `DELETE`\nrequests, will include an `_embedded` key in their response. The object\nrepresented by this key will contain the created or modified object. This\nobject is identical to what would be returned by a subsequent `GET` request\nfor the object referred to by the endpoint.\n"
  x-logo:
    url: https://docs.upsun.com/images/upsun-api.svg
    href: https://upsun.com/#section/Introduction
    altText: Upsun logo
servers:
- url: '{schemes}://api.upsun.com'
  description: The Upsun.com API gateway
  variables:
    schemes:
      default: https
security:
- OAuth2: []
tags:
- name: Orders
  description: 'These endpoints can be used to retrieve order information from our billing

    system. Here you can view information about your bill for our services,

    include the billed amount and a link to a PDF of the bill.

    '
paths:
  /orders/download:
    get:
      tags:
      - Orders
      summary: Download an invoice.
      operationId: download-invoice
      parameters:
      - name: token
        in: query
        description: JWT for invoice.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: An invoice PDF.
          content:
            application/pdf: {}
  /organizations/{organization_id}/orders:
    get:
      summary: List orders
      description: Retrieves orders for the specified organization.
      operationId: list-org-orders
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrganizationIDName'
      - $ref: '#/components/parameters/filter_order_status'
      - $ref: '#/components/parameters/filter_order_total'
      - $ref: '#/components/parameters/page'
      - $ref: '#/components/parameters/mode'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      $ref: '#/components/schemas/Order'
                  _links:
                    $ref: '#/components/schemas/ListLinks'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{organization_id}/orders/{order_id}:
    get:
      summary: Get order
      description: Retrieves an order for the specified organization.
      operationId: get-org-order
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrganizationIDName'
      - $ref: '#/components/parameters/OrderID'
      - $ref: '#/components/parameters/mode'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Order'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
  /organizations/{organization_id}/orders/{order_id}/authorize:
    post:
      summary: Create confirmation credentials for for 3D-Secure
      description: Creates confirmation credentials for payments that require online authorization
      operationId: create-authorization-credentials
      tags:
      - Orders
      parameters:
      - $ref: '#/components/parameters/OrganizationIDName'
      - $ref: '#/components/parameters/OrderID'
      responses:
        '200':
          description: Payment authorization credentials, if the payment is pending
          content:
            application/json:
              schema:
                type: object
                properties:
                  redirect_to_url:
                    type: object
                    description: URL information to complete the payment.
                    properties:
                      return_url:
                        type: string
                        description: Return URL after payment completion.
                      url:
                        type: string
                        description: URL for payment finalization.
                  type:
                    type: string
                    description: Required payment action type.
        '400':
          description: Bad Request when no authorization is required.
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not Found
          content:
            application/problem+json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    ListLinks:
      type: object
      properties:
        self:
          $ref: '#/components/schemas/Link'
        previous:
          $ref: '#/components/schemas/Link'
        next:
          $ref: '#/components/schemas/Link'
    LineItem:
      description: A line item in an order.
      properties:
        type:
          description: The type of line item.
          type: string
          enum:
          - project_plan
          - project_feature
          - project_subtotal
          - organization_plan
          - organization_feature
          - organization_subtotal
        license_id:
          description: The associated subscription identifier.
          type: number
          nullable: true
        project_id:
          description: The associated project identifier.
          type: string
          nullable: true
        product:
          description: Display name of the line item product.
          type: string
        sku:
          description: The line item product SKU.
          type: string
        total:
          description: Total price as a decimal.
          type: number
        total_formatted:
          description: Total price, formatted with currency.
          type: string
        components:
          description: The price components for the line item, keyed by type.
          type: object
          additionalProperties:
            $ref: '#/components/schemas/LineItemComponent'
        exclude_from_invoice:
          description: Line item should not be considered billable.
          type: boolean
      type: object
    Components:
      description: The components of the project
      properties:
        voucher/vat/baseprice:
          description: stub
          type: object
      type: object
    Error:
      description: ''
      type: object
      properties:
        status:
          type: string
        message:
          type: string
        code:
          type: number
        detail:
          type: object
        title:
          type: string
      title: ''
      x-examples:
        example-1:
          status: Invalid input
          message: This field is required.
          code: 400
          detail:
            field:
            - This field is required.
          title: Bad Request
    Link:
      type: object
      title: Link
      description: A hypermedia link to the {current, next, previous} set of items.
      properties:
        href:
          type: string
          description: URL of the link
    Address:
      description: The address of the user.
      properties:
        country:
          description: Two-letter country codes are used to represent countries and states
          type: string
          format: ISO ALPHA-2
        name_line:
          description: The full name of the user
          type: string
        premise:
          description: Premise (i.e. Apt, Suite, Bldg.)
          type: string
        sub_premise:
          description: Sub Premise (i.e. Suite, Apartment, Floor, Unknown.
          type: string
        thoroughfare:
          description: The address of the user
          type: string
        administrative_area:
          description: The administrative area of the user address
          type: string
          format: ISO ALPHA-2
        sub_administrative_area:
          description: The sub-administrative area of the user address
          type: string
        locality:
          description: The locality of the user address
          type: string
        dependent_locality:
          description: The dependant_locality area of the user address
          type: string
        postal_code:
          description: The postal code area of the user address
          type: string
      type: object
    Order:
      description: The order object.
      properties:
        id:
          description: The ID of the order.
          type: string
        status:
          description: The status of the subscription.
          type: string
          enum:
          - completed
          - past_due
          - pending
          - canceled
          - payment_failed_soft_decline
          - payment_failed_hard_decline
        owner:
          description: The UUID of the owner.
          type: string
          format: uuid
        address:
          $ref: '#/components/schemas/Address'
        company:
          description: The company name.
          type: string
        vat_number:
          description: An identifier used in many countries for value added tax purposes.
          type: string
        billing_period_start:
          description: The time when the billing period of the order started.
          type: string
          format: date-time
        billing_period_end:
          description: The time when the billing period of the order ended.
          type: string
          format: date-time
        billing_period_label:
          description: Descriptive information about the billing cycle.
          properties:
            formatted:
              description: The renderable label for the billing cycle.
              type: string
            month:
              description: The month of the billing cycle.
              type: string
            year:
              description: The year of the billing cycle.
              type: string
            next_month:
              description: The name of the next month following this billing cycle.
              type: string
          type: object
        billing_period_duration:
          description: The duration of the billing period of the order in seconds.
          type: integer
        paid_on:
          description: The time when the order was successfully charged.
          type: string
          format: date-time
          nullable: true
        total:
          description: The total of the order.
          type: integer
        total_formatted:
          description: The total of the order, formatted with currency.
          type: integer
        components:
          $ref: '#/components/schemas/Components'
        currency:
          description: The order currency code.
          type: string
        invoice_url:
          description: A link to the PDF invoice.
          type: string
        last_refreshed:
          description: The time when the order was last refreshed.
          type: string
          format: date-time
        invoiced:
          description: The customer is invoiced.
          type: boolean
        line_items:
          description: The line items that comprise the order.
          type: array
          items:
            $ref: '#/components/schemas/LineItem'
        _links:
          description: Links to related API endpoints.
          properties:
            invoices:
              description: Link to related Invoices API. Use this to retrieve invoices related to this order.
              properties:
                href:
                  description: URL of the link
                  type: string
              type: object
          type: object
      type: object
    LineItemComponent:
      description: A price component for a line item.
      properties:
        amount:
          description: The price as a decimal.
          type: number
        amount_formatted:
          description: The price formatted with currency.
          type: string
        display_title:
          description: The display title for the component.
          type: string
        currency:
          description: The currency code for the component.
          type: string
      type: object
  parameters:
    page:
      name: page
      in: query
      description: Page to be displayed. Defaults to 1.
      required: false
      schema:
        type: integer
        format: int32
    OrganizationIDName:
      in: path
      name: organization_id
      description: 'The ID of the organization.<br>

        Prefix with name= to retrieve the organization by name instead.

        '
      required: true
      schema:
        type: string
    filter_order_status:
      name: filter[status]
      in: query
      description: The status of the order.
      schema:
        type: string
        enum:
        - completed
        - past_due
        - pending
        - canceled
        - payment_failed_soft_decline
        - payment_failed_hard_decline
    OrderID:
      in: path
      name: order_id
      description: The ID of the order.
      required: true
      schema:
        type: string
    filter_order_total:
      name: filter[total]
      in: query
      description: The total of the order.
      schema:
        type: integer
    mode:
      name: mode
      in: query
      description: The output mode.
      schema:
        type: string
        enum:
        - details
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          tokenUrl: https://auth.api.platform.sh/oauth2/token
          refreshUrl: https://auth.api.platform.sh/oauth2/token
          scopes: {}
          authorizationUrl: https://auth.api.platform.sh/oauth2/authorize
      description: ''
    OAuth2Admin:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://auth.api.platform.sh/oauth2/token
          refreshUrl: ''
          scopes:
            admin: administrative operations
      description: ''
x-tagGroups:
- name: Organization Administration
  tags:
  - Organizations
  - Organization Members
  - Organization Invitations
  - Organization Projects
  - Add-ons
- name: Project Administration
  tags:
  - Project
  - Domain Management
  - Cert Management
  - Certificate Provisioner
  - Project Variables
  - Repository
  - Third-Party Integrations
  - Support
- name: Environments
  tags:
  - Environment
  - Environment Backups
  - Environment Type
  - Environment Variables
  - Routing
  - Source Operations
  - Runtime Operations
  - Deployment
  - Autoscaling
- name: User Activity
  tags:
  - Project Activity
  - Environment Activity
- name: Project Access
  tags:
  - Project Invitations
  - Teams
  - Team Access
  - User Access
- name: Account Management
  tags:
  - API Tokens
  - Connections
  - MFA
  - Users
  - User Profiles
  - SSH Keys
  - Plans
- name: Billing
  tags:
  - Organization Management
  - Subscriptions
  - Orders
  - Invoices
  - Discounts
  - Vouchers
  - Records
  - Profiles
- name: Global Info
  tags:
  - Project Discovery
  - References
  - Regions
- name: Internal APIs
  tags:
  - Project Settings
  - Environment Settings
  - Deployment Target
  - System Information
  - Container Profile