{ "type":"object",
  "title": "recurring",
  "name": "recurring",
  "description": "An recurring is used as an template for new invoices.",
  "properties":{
    "id":{
      "description":"Unique identifier - UUID",
      "identity":true,
      "readonly":true,
      "type":"string",
      "maxLength": 22,
      "minLength":22
    },
    "number":{
      "description": "Unique name to identify the document. Unlike all other document this one has no number schema and not auto assign",
      "type":"string",
      "required":true,
      "maxLength": 50
    },
    "address_field":{
      "description": "Receiver address, normally shown in envelope window. Defaults to client address_field if empty and client_id given.",
      "type":"string"
    },
    "date":{
      "description": "First date the recurring is issued. Not allowed to be in the past. YYYY-MM-DD",
      "format":"date",
      "type":"string",
      "required":true
    },
    "due_days":{
      "description": "Used to calculate the due date of the recurring. Useless if date and due date are present.",
      "type":"integer"
    },
    "final_date":{
      "description": "The last date the recurring is executed. YYYY-MM-DD",
      "format":"date",
      "type":"string",
      "required":true
    },
    "frequency":{
      "description": "Recurring frequency",
      "enum":["yearly", "monthly", "weekly", "quarterly", "biweekly", "sixmonthly"],
      "type":"string",
      "required":true
    },
    "payment_method":{
      "description": "How the document is being payed. Used in new payments.",
      "enum":["cash","bank_transfer","credit_card","paypal","direct_debit","cheque", "moneybookers", "premium_sms"],
      "type":"string"
    },
    "external_ref":{
      "description": "Some external reference, whatever this may be.",
      "type":"string",
      "maxLength": 255
    },
    "title":{
      "description": "The headline of a document. Use SK placeholders to prevent excessive typing e.g. 'Your recurring [number]'",
      "type":"string",
      "maxLength": 255
    },
    "notes_before":{
      "description": "Notes shown before the line items. Normally contains salutation and other introductional information. SK placeholders can be used.",
      "type":"string",
      "format":"text"
    },
    "notes_after":{
      "description": "Notes shown after the line items. Can contain information about payments, bank account or a thank-you message. SK placeholders can be used.",
      "type":"string",
      "format":"text"
    },
    "tag_list":{
      "description": "Space separated list of tags. Are split and saved as Tag objects on create, update.",
      "type":"string"
    },
    "language":{
      "description": "Should be a valid language short-code: de-DE, fr, en-GB; like defined in your account language menu. When the document is emailed or printed, a localized version of a multi-language template(email, pdf) will be used if available. Defaults to the clients language, if empty and a client is assigned.",
      "type":"string",
      "maxLength": 10
    },
    "currency":{
      "description": "Currency code as defined by the ISO 4217 standard (3-letter UPCASE: EUR, USD)",
      "type":"string",
      "maxLength": 3,
      "minLength": 3
    },
    "client":{
      "description": "DEPRECATED: use contact",
      "readonly":true,
      "type":"object",
      "properties":{"$ref":"./client.json#properties"}
    },
    "client_id":{
      "description": "DEPRECATED: use contact_id",
      "type":"string",
      "maxLength": 22,
      "minLength":22
    },
    "contact":{
      "description": "The contact for the document. Use contact_id field to set a contact.",
      "readonly":true,
      "type":"object",
      "properties":{"$ref":"./contact.json#properties"}
    },
    "contact_id":{
      "description": "The contact uuid. When assigning a contact its language, currency, address_field (due days, cash discount) values are used for the document if those doc-fields are not set.",
      "type":"string",
      "maxLength": 22,
      "minLength":22
    },
    "team_id":{
      "description": "A team uuid. If set only the team and its parent teams can see the record.",
      "type":"string",
      "maxLength": 22,
      "minLength":22
    },
    "line_items":{
      "description": "DEPRECATED use items",
      "type":"array",
      "properties":{"$ref":"./line_item.json#properties"}
    },
    "items":{
      "description": "Items for the document. Access items of all types including divider and sub_total items. GOTCHAs when using items instead of line_items: You MUST set the type field(CamelCasesItem class name) on each item. You cannot use both, the line_items array is stronger for backward compat.",
      "type":"array",
      "default": "any",
      "minItems": 0,
      "items": [{ "$ref": "./line_item.json#properties"},
                { "$ref":  "./divider_item.json#properties"},
                { "$ref": "./sub_total_item.json#properties"}]
    },
    "created_at":{
      "description": "Date the object was created in SK. Never changes afterwards.",
      "format":"date-time",
      "readonly":true,
      "type":"string"
    },
    "updated_at":{
      "description": "Date the object was edited in SK.",
      "format":"date-time",
      "readonly":true,
      "type":"string"
    },
    "lock_version":{
      "description": "Auto-incremented to prevent concurrent updates. First save wins and increments version. ",
      "type":"integer"
    },
    "gross_total":{
      "description": "Gross total of all line items, 2 decimals places",
      "readonly":true,
      "type":"number"
    },
    "tax_total":{
      "description": "Tax total, 2 decimals places",
      "readonly":true,
      "type":"number"
    },
    "net_total":{
      "description": "Net total, 2 decimals places",
      "readonly":true,
      "type":"number"
    },
    "net_total_base":{
      "description": "Net total, 6 decimal places incl. discount",
      "readonly":true,
      "type":"number"
    },
    "cost_total":{
      "description": "Cost total of all line items, 2 decimals places in document currency.",
      "readonly":true,
      "type":"number"
    },
    "gross_margin_total":{
      "description": "Total gross margin across all line items. Calculated from net_total-cost_total.",
      "readonly":true,
      "type":"number"
    },
    "gross_margin_pct":{
      "description": "Percentage of gross profit to cost of items sold. Calculated from gross_margin_total/net_total*100",
      "readonly":true,
      "type":"number"
    },
    "pdf_template_id":{
      "description": "The PDF template used for printing the invoice when auto sending. Required when auto_send'ing is enabled.",
      "type":"string",
      "maxLength": 22,
      "minLength":22
    },
    "email_template_id":{
      "description": "The Email template used for the email in auto sending. Required when auto_send'ing is enabled.",
      "type":"string",
      "maxLength": 22,
      "minLength":22
    },
    "auto_send":{
      "description": "Enable automatic sending of new invoices created from the recurring. Opens the invoice, creates a PDF and sends an email to the contact. GOTCHA's: check PDF-, Email-Template, SMTP Settings and of course the contacts email address! Since new recurrings which start today directly create new invoices, they are also SEND if auto_send is true!! If something fails, we'll send an error-email to the user who created the recurring. For success infos you can add yourself to the BCC of the email template or",
      "default": null,
      "type": "string",
      "enum":["email"]
    }
  },
  "links":[
    { "rel": "self",
      "href": "recurrings/{id}"
    },
    { "rel": "instances",
      "href": "recurrings",
      "properties" : {
        "page":{
          "title" : "Page",
          "description": "In paginated results set the page to look for",
          "type":"number"
        },
        "per_page":{
          "title" : "Per page",
          "description": "Results per page. Default is 10, max is 100",
          "type":"number"
        },
        "filter[q]":{
          "title" : "Search",
          "description": "Search in title, number, address field",
          "type":"string"
        },
        "filter[tags]":{
          "title" : "Tags",
          "description": "Filter by a space delimited list of tags",
          "type":"string"
        },
        "filter[from]":{
          "title" : "From date",
          "description": "Objects with a date after the date. YYYY-MM-DD",
          "format" : "date",
          "type" : "string"
        },
        "filter[to]":{
          "title" : "To date",
          "description": "Objects with date before the date",
          "format" : "date",
          "type" : "string"
        },
        "filter[created_at_from]":{
          "title" : "From date",
          "description": "Objects with a creation date after the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z",
          "format" : "date-time",
          "type" : "string"
        },
        "filter[created_at_to]":{
          "title" : "To date",
          "description": "Objects with a creation date before the date, including given datetime. ISO 8601 format YYY-MM-DDThh:mm:ss+z",
          "format" : "date-time",
          "type" : "string"
        },
        "filter[languages]":{
          "title" : "Languages",
          "description": "A list of language codes, comma separated",
          "type" : "string"
        },
        "filter[client_ids]":{
          "title" : "Clients",
          "description": "DEPRECATED use contact_ids",
          "type" : "string"
        },
        "filter[contact_ids]":{
          "title" : "Contacts",
          "description": "A single or a list of contact uuids, comma separated",
          "type" : "string"
        },
        "filter[ids]":{
          "title" : "Documents",
          "description": "A single or a list of document uuids, comma separated",
          "type" : "string"
        },
        "filter[creator_ids]":{
          "title" : "Creator",
          "description": "Objects created by the given users uuids, comma separated",
          "type" : "string"
        },
        "filter[product_ids]":{
          "title" : "Products",
          "description": "Documents using the given product uuids(comma separated) in their line items.",
          "type" : "string"
        },
        "sort_by":{
          "title" : "Sort by",
          "description": "Sort the results by the given field => number",
          "enum":["title", "number", "created_at", "updated_at", "price_total"],
          "type": "string"
        },
        "sort":{
          "title" : "Sort",
          "enum":["ASC","DESC"],
          "description": "Sort the results in ASC or DESC",
          "type": "string"
        }
      }
    },
    { "rel": "destroy",
      "href": "recurrings/{id}",
      "method": "DELETE"
    },
    { "rel": "update",
      "href": "recurrings/{id}",
      "method": "PUT"
    },
    { "rel": "create",
      "href": "recurrings",
      "method": "POST",
      "properties" : {
        "source" : {
          "title" : "Source document id",
          "description": "Copies the source(excl. number,date) and returns a new draft document. You can pass any document type(e.g. invoice, order). Fields passed with the object(e.g. notes, title, address_field) are not overwritten.",
          "type" : "string"
        }
      }
    },
    { "rel": "invoices",
      "href": "invoices?filter[recurring_ids]={id}"
    },
    { "rel": "attachments",
      "href": "recurrings/{id}/attachments"
    },
    { "rel": "comments",
      "href": "recurrings/{id}/comments"
    }
  ]
}