Brand Design Ltd.

Read the service catalogue: names, prices, currency and terms. No credentials needed. All amounts are integers in the minor unit; 100000 means 1000.00 EUR.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Read the commerce manifest: protocol, endpoints, authentication scheme, payment instrument and limits. No credentials needed.

{
  "type": "object",
  "properties": {},
  "additionalProperties": false
}

Register yourself and receive a client identifier and a secret. No approval and no prior arrangement. The secret is returned once and cannot be recovered. Put them in the Authorization header as "Bearer <clientId>:<secret>" for the other tools.

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Your name, 2 to 80 characters."
    },
    "contact": {
      "type": "string",
      "description": "A https:// or mailto: URL at which a human can reach whoever runs you."
    }
  },
  "required": [
    "name",
    "contact"
  ],
  "additionalProperties": false
}

Place an order for a service. Needs credentials. Returns the order id, the offer and an accessToken you must keep for the following calls. The offer is pinned to the hash of the service page; accept_offer needs offer.version and offer.terms.<language>.hash from it. Services without a catalogue price return an offer with no total and wait for a person to price it. Errors: MISSING_<field> when a required brief field is absent, UNEXPECTED_FIELD when the brief has a key the service does not declare.

{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The clientId returned by register_agent."
    },
    "secret": {
      "type": "string",
      "description": "Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The secret returned by register_agent."
    },
    "service": {
      "type": "string",
      "description": "Service id: one of the keys of catalog.services, as returned by the catalog tool."
    },
    "language": {
      "type": "string",
      "enum": [
        "bg",
        "en"
      ],
      "description": "Language of the offer, the terms and the documents. Defaults to en."
    },
    "brief": {
      "type": "object",
      "additionalProperties": {
        "type": "string"
      },
      "description": "One string per field the catalogue lists under this service in catalog.services.<service>.fields. Use each field id as the key. Fields with required: true must be present; the max value is the length limit. No other keys are accepted."
    },
    "lines": {
      "type": "array",
      "maxItems": 20,
      "description": "Only for services that have catalog.services.<service>.configurator. One entry per item: item is an id from configurator.items; qty is the number of designs, or the number of pages when the item has per \"page\", within item.qty min and max; options maps every option id of the item to one of its value ids; note is free text, required when the item has noteRequired. The price is computed by the seller from the catalogue; never send a price. If any chosen item has price null, the order waits for a person to price it.",
      "items": {
        "type": "object",
        "required": [
          "item"
        ],
        "additionalProperties": false,
        "properties": {
          "item": {
            "type": "string"
          },
          "qty": {
            "type": "integer"
          },
          "options": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "note": {
            "type": "string",
            "maxLength": 500
          }
        }
      }
    },
    "printQuote": {
      "type": "boolean",
      "description": "Only with lines: the buyer would like a print quote once the design work has started. Printing is not part of this order."
    },
    "idempotencyKey": {
      "type": "string",
      "description": "Your own key, so a repeated call does not create a second order."
    }
  },
  "required": [
    "service",
    "brief"
  ],
  "additionalProperties": false
}

Accept the offer on behalf of the buyer. Needs credentials. This locks the billing identity, the offer version and the hash of the terms as they stand at this moment. A later change to the website cannot pass for what was agreed. Errors: OFFER_CHANGED (409) if the offer or the terms changed since you read them; read order_status and use the new values. OFFER_EXPIRED (409) 30 days after the order. MANUAL_OFFER_REQUIRED (409) while a person has not priced the service yet.

{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The clientId returned by register_agent."
    },
    "secret": {
      "type": "string",
      "description": "Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The secret returned by register_agent."
    },
    "order": {
      "type": "string",
      "description": "The order id returned by create_order."
    },
    "accessToken": {
      "type": "string",
      "description": "The accessToken returned by create_order."
    },
    "offerVersion": {
      "type": "string",
      "description": "offer.version from the order, copied exactly."
    },
    "termsHash": {
      "type": "string",
      "description": "SHA-256 of the terms page in the language of the order: offer.terms.<language>.hash from the order, copied exactly. Sending it confirms that the buyer accepts those terms."
    },
    "billing": {
      "type": "object",
      "description": "The buyer as it will appear on the invoice and the contract. For type company, company, registration and representative are also required. For type person, leave out company, registration, vat and representative. No other keys are accepted.",
      "required": [
        "type",
        "fullName",
        "email",
        "country",
        "city",
        "address"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "person",
            "company"
          ]
        },
        "fullName": {
          "type": "string",
          "minLength": 3,
          "maxLength": 150,
          "description": "Full name of the buyer, or of the contact person for a company."
        },
        "email": {
          "type": "string",
          "maxLength": 254
        },
        "phone": {
          "type": "string",
          "minLength": 5,
          "maxLength": 40,
          "description": "Optional."
        },
        "country": {
          "type": "string",
          "pattern": "^[A-Za-z]{2}$",
          "description": "ISO 3166-1 alpha-2 code, for example BG."
        },
        "city": {
          "type": "string",
          "minLength": 1,
          "maxLength": 100
        },
        "address": {
          "type": "string",
          "minLength": 3,
          "maxLength": 250
        },
        "company": {
          "type": "string",
          "minLength": 2,
          "maxLength": 200,
          "description": "Company only. Registered name."
        },
        "registration": {
          "type": "string",
          "minLength": 4,
          "maxLength": 40,
          "description": "Company only. Company registration number; for country BG the 9- or 13-digit EIK."
        },
        "vat": {
          "type": "string",
          "minLength": 4,
          "maxLength": 40,
          "description": "Company only. Optional VAT number."
        },
        "representative": {
          "type": "string",
          "minLength": 3,
          "maxLength": 150,
          "description": "Company only. The person who legally represents the company."
        }
      },
      "if": {
        "properties": {
          "type": {
            "const": "company"
          }
        }
      },
      "then": {
        "required": [
          "company",
          "registration",
          "representative"
        ]
      },
      "additionalProperties": false
    }
  },
  "required": [
    "order",
    "accessToken",
    "offerVersion",
    "termsHash",
    "billing"
  ],
  "additionalProperties": false
}

Start payment for a stage. Needs credentials. Without sharedPaymentToken you receive a hosted payment session, which you may complete yourself with a payment instrument issued to you, or hand to the person you act for. With a delegated shared payment token the payment settles directly. On-chain payment is not accepted. Errors: OFFER_EXPIRED (409) for an advance after 30 days, FINAL_NOT_RELEASED (409) when the final payment is not open yet, PAYMENTS_DISABLED (503).

{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The clientId returned by register_agent."
    },
    "secret": {
      "type": "string",
      "description": "Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The secret returned by register_agent."
    },
    "order": {
      "type": "string",
      "description": "The order id returned by create_order."
    },
    "accessToken": {
      "type": "string",
      "description": "The accessToken returned by create_order."
    },
    "stage": {
      "type": "string",
      "enum": [
        "advance",
        "final"
      ],
      "description": "advance: the first payment, open after accept_offer. It is 50% of the total, or the whole total when the service is paid at once (paymentPlan single in the catalogue). final: the remaining 50%, open only after the advance is paid and the seller has released the work for final payment. Defaults to advance."
    },
    "sharedPaymentToken": {
      "type": "string",
      "description": "Only for delegated payment without a hosted page: a Stripe shared payment token granted to the seller profile in manifest.payment.networkBusinessProfile. Leave it out to receive a hosted payment session instead."
    }
  },
  "required": [
    "order",
    "accessToken"
  ],
  "additionalProperties": false
}

Read the current state of the order, its offer and its payments, including the invoice number once one has been issued. Needs credentials.

{
  "type": "object",
  "properties": {
    "clientId": {
      "type": "string",
      "description": "Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The clientId returned by register_agent."
    },
    "secret": {
      "type": "string",
      "description": "Required unless you authenticate with the Authorization header (Bearer <clientId>:<secret>, or an OAuth access token issued for this server). The secret returned by register_agent."
    },
    "order": {
      "type": "string",
      "description": "The order id returned by create_order."
    },
    "accessToken": {
      "type": "string",
      "description": "The accessToken returned by create_order."
    }
  },
  "required": [
    "order",
    "accessToken"
  ],
  "additionalProperties": false
}