Surfing Dog Inbox

Name, time zone, currency, languages and the item types this business accepts.

{
  "type": "object",
  "properties": {},
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Bookable services with duration and price. A price per person (price.per = person) is for each person in the booking: send partySize, and the total is the price times it.

{
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "maxLength": 200
    },
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Orderable products with prices in minor units.

{
  "type": "object",
  "properties": {
    "cursor": {
      "type": "string",
      "maxLength": 200
    },
    "limit": {
      "default": 50,
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "q": {
      "type": "string",
      "maxLength": 100
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Free start times for a service between two instants (at most 14 days). A time that has started, or that starts within the business's minimum notice, is not offered.

{
  "type": "object",
  "properties": {
    "service_id": {
      "type": "string",
      "minLength": 1
    },
    "from": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "Start of the window to search, ISO 8601."
    },
    "to": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "End of the window, at most 14 days after from."
    },
    "party_size": {
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    }
  },
  "required": [
    "service_id",
    "from",
    "to"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Ask for a price on something custom. Creates a quote_request item.

{
  "type": "object",
  "properties": {
    "payload": {
      "type": "object",
      "properties": {
        "itemOffered": {
          "type": "object",
          "properties": {
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            },
            "sku": {
              "type": "string",
              "maxLength": 100
            },
            "serviceId": {
              "type": "string"
            },
            "productId": {
              "type": "string"
            }
          },
          "required": [
            "name"
          ]
        },
        "quantity": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9007199254740991
        },
        "description": {
          "type": "string",
          "minLength": 1,
          "maxLength": 5000
        },
        "budget": {
          "type": "object",
          "properties": {
            "value": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "currency": {
              "type": "string",
              "minLength": 3,
              "maxLength": 3
            }
          },
          "required": [
            "value",
            "currency"
          ]
        },
        "requestedFor": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "deliveryAddress": {
          "type": "object",
          "properties": {
            "streetAddress": {
              "type": "string",
              "maxLength": 200
            },
            "addressLocality": {
              "type": "string",
              "maxLength": 100
            },
            "addressRegion": {
              "type": "string",
              "maxLength": 100
            },
            "postalCode": {
              "type": "string",
              "maxLength": 20
            },
            "addressCountry": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          }
        }
      },
      "required": [
        "itemOffered",
        "description"
      ]
    },
    "contact": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
        },
        "phone": {
          "type": "string",
          "maxLength": 40
        },
        "locale": {
          "type": "string",
          "maxLength": 12
        }
      }
    },
    "message": {
      "type": "string",
      "maxLength": 20000
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "payload"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Request a service at a time. Check availability first. A fixed-price service costs the business's price from list_services; a different totalPrice you send is only noted for the business. A priced booking binds your person only once they confirmed it: without terms_sha nothing is sent, and you get the summary to show them (confirm.summary, confirm.terms_sha); call again with that terms_sha on their clear yes. Returns the item and, if you have no account, an access_token.

{
  "type": "object",
  "properties": {
    "payload": {
      "type": "object",
      "properties": {
        "reservationFor": {
          "type": "object",
          "properties": {
            "serviceId": {
              "type": "string",
              "minLength": 1
            },
            "name": {
              "type": "string",
              "minLength": 1,
              "maxLength": 200
            }
          },
          "required": [
            "serviceId",
            "name"
          ]
        },
        "startTime": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "endTime": {
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "partySize": {
          "type": "integer",
          "minimum": 1,
          "maximum": 1000
        },
        "totalPrice": {
          "type": "object",
          "properties": {
            "value": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "currency": {
              "type": "string",
              "minLength": 3,
              "maxLength": 3
            }
          },
          "required": [
            "value",
            "currency"
          ]
        },
        "personalised": {
          "type": "object",
          "properties": {
            "listPrice": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "currency": {
                  "type": "string",
                  "minLength": 3,
                  "maxLength": 3
                }
              },
              "required": [
                "value",
                "currency"
              ]
            },
            "says": {
              "type": "string",
              "maxLength": 200
            }
          },
          "required": [
            "listPrice"
          ]
        },
        "resourceId": {
          "type": "string"
        },
        "notes": {
          "type": "string",
          "maxLength": 5000
        }
      },
      "required": [
        "reservationFor",
        "startTime",
        "endTime"
      ]
    },
    "contact": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
        },
        "phone": {
          "type": "string",
          "maxLength": 40
        },
        "locale": {
          "type": "string",
          "maxLength": 12
        }
      }
    },
    "message": {
      "type": "string",
      "maxLength": 20000
    },
    "terms_sha": {
      "description": "The fingerprint of the terms your person confirmed (details.terms_sha of the 409 confirm_terms a priced request without it gets). Nothing is sent to the business without it when the request carries a price.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{43}$"
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "payload"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Order products. Prices are in minor units. A line naming a product (productId or sku) costs the business's price from list_products, and the total follows; a different price you send is only noted for the business. A line naming no product waits for the business to price it. A priced order binds your person only once they confirmed it: without terms_sha nothing is sent, and you get the summary to show them (confirm.summary, confirm.terms_sha); call again with that terms_sha on their clear yes.

{
  "type": "object",
  "properties": {
    "payload": {
      "type": "object",
      "properties": {
        "orderedItem": {
          "minItems": 1,
          "maxItems": 200,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "productId": {
                "type": "string"
              },
              "sku": {
                "type": "string",
                "maxLength": 100
              },
              "name": {
                "type": "string",
                "minLength": 1,
                "maxLength": 200
              },
              "quantity": {
                "type": "integer",
                "minimum": 1,
                "maximum": 9007199254740991
              },
              "price": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "currency": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  }
                },
                "required": [
                  "value",
                  "currency"
                ]
              },
              "listPrice": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "currency": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  }
                },
                "required": [
                  "value",
                  "currency"
                ]
              }
            },
            "required": [
              "name",
              "quantity",
              "price"
            ]
          }
        },
        "totalPrice": {
          "type": "object",
          "properties": {
            "value": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "currency": {
              "type": "string",
              "minLength": 3,
              "maxLength": 3
            }
          },
          "required": [
            "value",
            "currency"
          ]
        },
        "personalised": {
          "type": "object",
          "properties": {
            "listPrice": {
              "type": "object",
              "properties": {
                "value": {
                  "type": "integer",
                  "minimum": 0,
                  "maximum": 9007199254740991
                },
                "currency": {
                  "type": "string",
                  "minLength": 3,
                  "maxLength": 3
                }
              },
              "required": [
                "value",
                "currency"
              ]
            },
            "says": {
              "type": "string",
              "maxLength": 200
            }
          },
          "required": [
            "listPrice"
          ]
        },
        "billingAddress": {
          "type": "object",
          "properties": {
            "streetAddress": {
              "type": "string",
              "maxLength": 200
            },
            "addressLocality": {
              "type": "string",
              "maxLength": 100
            },
            "addressRegion": {
              "type": "string",
              "maxLength": 100
            },
            "postalCode": {
              "type": "string",
              "maxLength": 20
            },
            "addressCountry": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          }
        },
        "shippingAddress": {
          "type": "object",
          "properties": {
            "streetAddress": {
              "type": "string",
              "maxLength": 200
            },
            "addressLocality": {
              "type": "string",
              "maxLength": 100
            },
            "addressRegion": {
              "type": "string",
              "maxLength": 100
            },
            "postalCode": {
              "type": "string",
              "maxLength": 20
            },
            "addressCountry": {
              "type": "string",
              "minLength": 2,
              "maxLength": 2
            }
          }
        },
        "delivery": {
          "type": "object",
          "properties": {
            "method": {
              "type": "string",
              "enum": [
                "pickup",
                "delivery",
                "digital"
              ]
            },
            "when": {
              "type": "string",
              "format": "date-time",
              "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
            }
          },
          "required": [
            "method"
          ]
        },
        "paymentMethod": {
          "type": "string",
          "maxLength": 60
        },
        "notes": {
          "type": "string",
          "maxLength": 5000
        }
      },
      "required": [
        "orderedItem",
        "totalPrice"
      ]
    },
    "contact": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
        },
        "phone": {
          "type": "string",
          "maxLength": 40
        },
        "locale": {
          "type": "string",
          "maxLength": 12
        }
      }
    },
    "message": {
      "type": "string",
      "maxLength": 20000
    },
    "terms_sha": {
      "description": "The fingerprint of the terms your person confirmed (details.terms_sha of the 409 confirm_terms a priced request without it gets). Nothing is sent to the business without it when the request carries a price.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{43}$"
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "payload"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

The current state of an item you created, in the business's words: what it proposed and waits for your person to answer (offer, with its terms_sha), who it waits on, what they can do next, and the conversation so far (thread: the business's replies and your person's messages).

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Accept another time the business proposed for a booking, its quote, its changes to an order, or a change it asks for to a confirmed booking or an accepted order (offer.kind change: the promise moves). This binds your person, so send terms_sha — offer.terms_sha from get_item_status — only after they said yes to offer.human, and offer_id (offer.id) so an answer to an offer since replaced does nothing. Without terms_sha nothing is booked: you get the terms to show them. An accepted quote becomes a confirmed booking or order (linked). A yes to a change that can no longer be made online goes to a person there instead (passed_on), and what was agreed stands.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "offer_id": {
      "description": "The offer you answer: offer.id from get_item_status. If the business has replaced it since, nothing is done (409 offer_changed, with the current one).",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "terms_sha": {
      "description": "The fingerprint of the terms your person said yes to: offer.terms_sha from get_item_status. Leave it out to be told the terms first; nothing is booked without it.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{43}$"
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Say no to another time or to changes the business proposed (the booking request or the order is closed) or to its quote. To a change it asks for to a confirmed booking or an accepted order, no keeps what was agreed; on a change your person asked for (requested_change), it takes that back. Add reason (and reason_code) for anything your person wants the business to know.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "offer_id": {
      "description": "The offer you answer: offer.id from get_item_status. If the business has replaced it since, nothing is done (409 offer_changed, with the current one).",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "reason": {
      "description": "Anything your person wants the business to know.",
      "type": "string",
      "maxLength": 2000
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "price_sensitivity",
        "timing_deferred",
        "quantity",
        "delivery",
        "returns_policy",
        "other"
      ],
      "description": "Why: price_sensitivity, timing_deferred, quantity, delivery, returns_policy or other."
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Instead of the time the business proposed, ask for another: start_time must be one of the free times check_availability lists (the end follows the service's length). The business confirms it or proposes again. On a confirmed booking it asks the business to move it (the end keeps the booking's length), and the booking stays as agreed until the business says yes. After a few rounds, or past the changes a booking may have, a person there answers it instead (passed_on).

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "start_time": {
      "type": "string",
      "format": "date-time",
      "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$",
      "description": "The start your person would like instead: one of the free times check_availability lists. The end follows the service's length."
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id",
    "start_time"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Answer what the business proposed with only what your person would change: another start_time (a booking: one of the free times check_availability lists; a quote request: the time it is for), other quantities for the lines of changes it suggested to an order (by index in offer.terms.lines; 0 drops one), another delivery_when, or how many (quantity) for a quote request. It goes back to the business as their request. On a confirmed booking or an accepted order it asks for a change to what was agreed (lines by index in the order's orderedItem), which stands until the business says yes. A price of their own is their answer only where get_business_profile says price_negotiable: total_price for a time it proposed (start_time optional), unit_price on lines of changes to an order; it goes back to the business, which takes it or answers. Otherwise — a price where the business sets its prices, on a quote, on something it does not haggle, or asked too often — it goes to a person there as their message, as do a note alone and a suggestion after a few rounds (passed_on): never refused, and what the business proposed, or what was agreed, still stands.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "offer_id": {
      "description": "The offer you answer: offer.id from get_item_status. If the business has replaced it since, nothing is done (409 offer_changed, with the current one).",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "terms": {
      "type": "object",
      "properties": {
        "start_time": {
          "description": "Another start: for a booking, one of the free times check_availability lists (the end follows the service's length); for a quote request, the time it is for.",
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "party_size": {
          "description": "Another number of people.",
          "type": "integer",
          "minimum": 1,
          "maximum": 1000
        },
        "quantity": {
          "description": "How many, for a quote request.",
          "type": "integer",
          "minimum": 1,
          "maximum": 1000000
        },
        "lines": {
          "description": "For changes the business suggested to an order: other quantities for its lines, by index in offer.terms.lines; 0 drops a line. unit_price, a price of your own for a line, only where the business's profile says price_negotiable.",
          "maxItems": 200,
          "type": "array",
          "items": {
            "type": "object",
            "properties": {
              "index": {
                "type": "integer",
                "minimum": 0,
                "maximum": 199
              },
              "quantity": {
                "type": "integer",
                "minimum": 0,
                "maximum": 1000000
              },
              "unit_price": {
                "type": "object",
                "properties": {
                  "value": {
                    "type": "integer",
                    "minimum": 0,
                    "maximum": 9007199254740991
                  },
                  "currency": {
                    "type": "string",
                    "minLength": 3,
                    "maxLength": 3
                  }
                },
                "required": [
                  "value",
                  "currency"
                ]
              }
            },
            "required": [
              "index",
              "quantity"
            ]
          }
        },
        "delivery_when": {
          "description": "Another delivery date, for an order.",
          "type": "string",
          "format": "date-time",
          "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$"
        },
        "total_price": {
          "description": "A price of your own for a time the business proposed. Taken as your answer only where the business's profile says price_negotiable; otherwise it goes to a person there as your message, and what it proposed still stands.",
          "type": "object",
          "properties": {
            "value": {
              "type": "integer",
              "minimum": 0,
              "maximum": 9007199254740991
            },
            "currency": {
              "type": "string",
              "minLength": 3,
              "maxLength": 3
            }
          },
          "required": [
            "value",
            "currency"
          ]
        }
      },
      "description": "Only what your person would change."
    },
    "note": {
      "description": "Anything your person wants the business to know.",
      "type": "string",
      "maxLength": 2000
    },
    "reason_code": {
      "type": "string",
      "enum": [
        "price_sensitivity",
        "timing_deferred",
        "quantity",
        "delivery",
        "returns_policy",
        "other"
      ],
      "description": "Why: price_sensitivity, timing_deferred, quantity, delivery, returns_policy or other."
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id",
    "terms"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Answer what the business asked about an item (get_item_status says it needs a detail). The item moves on; on any other item your details are kept as a message for the business.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "details": {
      "type": "string",
      "minLength": 1,
      "maxLength": 5000,
      "description": "The answer to what the business asked."
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id",
    "details"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Your person withdraws from their booking (one they paid for) or order, within the period the business states (withdrawal on get_item_status). Two steps: without confirm_withdrawal nothing is sent and you get the statement to show them (confirm.statement); send confirm_withdrawal: true on their yes. Before the goods went out the order ends and what was paid is refunded; once they reached your person, the goods come back (lines: only some of them) and are refunded. The business emails a copy. Never refused: past the period, or for something that cannot be returned, it goes to a person there instead (passed_on), or becomes a return under the business's own policy.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "confirm_withdrawal": {
      "description": "true once your person confirmed the statement you were shown. Left out, nothing is sent: you get the statement.",
      "type": "boolean"
    },
    "lines": {
      "description": "Once the goods reached them: only these lines (by index in the order's orderedItem), and how many of each.",
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 199
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000
          }
        },
        "required": [
          "index",
          "quantity"
        ]
      }
    },
    "note": {
      "description": "Anything your person wants to tell the business.",
      "type": "string",
      "maxLength": 2000
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Once an order's goods reached your person: ask to send them back. reason faulty, not_as_described or wrong_item (the legal guarantee: it costs them nothing), or changed_mind (a withdrawal while the period runs, agreed at once; after it, a return the business answers under its own policy). lines: which, by index in orderedItem, and how many; all when left out. The return comes back as linked; get_item_status lists it under refunds.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "reason": {
      "type": "string",
      "enum": [
        "changed_mind",
        "faulty",
        "wrong_item",
        "not_as_described",
        "other"
      ],
      "description": "Why: changed_mind, faulty, wrong_item, not_as_described or other."
    },
    "lines": {
      "description": "Which lines of the order (by index in orderedItem), and how many of each; all of them when left out.",
      "maxItems": 200,
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "index": {
            "type": "integer",
            "minimum": 0,
            "maximum": 199
          },
          "quantity": {
            "type": "integer",
            "minimum": 1,
            "maximum": 1000000
          }
        },
        "required": [
          "index",
          "quantity"
        ]
      }
    },
    "wants": {
      "description": "What your person would like: a refund, an exchange, or credit.",
      "type": "string",
      "enum": [
        "refund",
        "exchange",
        "credit"
      ]
    },
    "note": {
      "type": "string",
      "maxLength": 2000
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id",
    "reason"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Cancel an item you created. After the business's cancellation window, a confirmed booking is cancelled late where the business records late cancellations (it may count against the customer), and refused where it does not.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "reason": {
      "type": "string",
      "maxLength": 2000
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Start a conversation, or reply on an item you own.

{
  "type": "object",
  "properties": {
    "item_id": {
      "description": "Reply on an existing item; omit to start a new conversation.",
      "type": "string",
      "minLength": 1
    },
    "subject": {
      "type": "string",
      "maxLength": 500
    },
    "body": {
      "type": "string",
      "minLength": 1,
      "maxLength": 20000
    },
    "contact": {
      "type": "object",
      "properties": {
        "name": {
          "type": "string",
          "maxLength": 200
        },
        "email": {
          "type": "string",
          "format": "email",
          "pattern": "^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"
        },
        "phone": {
          "type": "string",
          "maxLength": 40
        },
        "locale": {
          "type": "string",
          "maxLength": 12
        }
      }
    },
    "message_id": {
      "type": "string",
      "minLength": 1,
      "maxLength": 998
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "idempotency_key": {
      "description": "Same key + same request = same answer. Required for agents.",
      "type": "string",
      "minLength": 1,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "body"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

Counter-sign a receipt this item earned, so both sides hold it: a promise, a change both sides agreed to it (kind amended), how it ended, or a refund's. Read the item to find its receipts; then send a compact JWS signed with your own Ed25519 key — header {alg:'EdDSA', typ:'sdi-receipt-ack+jws', jwk:<your public jwk>}, payload {rcp:<receipt id>, sha:<base64url(SHA-256(receipt jws))>, iat:<unix seconds>}. The instance verifies it against the key you carry and keeps it. Acknowledging twice is harmless.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "counter_signature": {
      "description": "A compact JWS by the customer's agent, EdDSA, header carrying its Ed25519 public `jwk`, payload `{\"rcp\": \"<receipt id>\", \"sha\": \"<base64url(SHA-256(receipt JWS))>\", \"iat\": <unix seconds>}`. Or, for an agent that signs its requests instead (sdi-agent/1) and carries a pass reference, `receipt_id` alone.",
      "type": "string",
      "minLength": 1,
      "maxLength": 8192
    },
    "receipt_id": {
      "description": "The receipt to acknowledge, for an agent that signs this request (sdi-agent/1) with a key delegated to the pass reference it sends: the inbox forwards the signature to the network (ADR-017 §3.4). Send this or counter_signature.",
      "type": "string",
      "minLength": 1,
      "maxLength": 64
    },
    "receipt": {
      "description": "The receipt JWS being acknowledged, if you want the instance to check it is the one it holds.",
      "type": "string",
      "minLength": 1,
      "maxLength": 8192
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "pass": {
      "description": "The person's passes (sdpass1_…), space-separated, at most 8: presented to the network that issued each, so the business recognises the customer. Or send them in the Sdi-Pass header. Never stored.",
      "type": "string",
      "maxLength": 1608
    },
    "key": {
      "description": "The person's key (sdkey1_…), if that is all you have: it is exchanged once for a pass, which comes back in identity.passes — keep the pass and send it next time instead. Never stored.",
      "type": "string",
      "maxLength": 200
    }
  },
  "required": [
    "item_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}

When a result says identity.recognised is weak, the person gave the email of a customer the business knows. Call this with item_id and access_token to email them six digits; ask the person for the code and call it again with code. Then the business recognises them.

{
  "type": "object",
  "properties": {
    "item_id": {
      "type": "string",
      "minLength": 1
    },
    "access_token": {
      "description": "Capability secret returned when the item was created without an account.",
      "type": "string",
      "minLength": 16,
      "maxLength": 200
    },
    "code": {
      "description": "The six digits the customer received. Omit to have them sent.",
      "type": "string",
      "pattern": "^[0-9]{6}$"
    }
  },
  "required": [
    "item_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema"
}